# Syrenka Agent API

Text-only personal agent. Speech-to-text and text-to-speech happen on YOUR side;
this server only ever exchanges text.

BASE: http://mateusz-desktop.tail96606f.ts.net
AUTH: Authorization: Bearer <token>   (every route except /health and the docs)
      The token IS the identity. There is no username on the wire and you cannot
      act as another user.

## REST
GET /health   (no auth)
    Liveness. Returns 200 even while warming so a container healthcheck does not restart-loop during first-boot indexing.
GET /status
    Agent state, registered tools, live sessions and host metrics.
GET /tools
    Every registered tool with the JSON Schema the model sees.
GET /history
    Your own recent turns. Scoped to the calling token; you cannot read anyone else's.

## WebSocket  ws://mateusz-desktop.tail96606f.ts.net/ws
Authenticate on the handshake with the same Authorization header. Browsers that
cannot set headers may instead offer subprotocols: "syrenka.v1, bearer.<token>".
A token in the query string is rejected — those leak into proxy logs.

Send:
  {"type":"turn", text: string, imageIds?: string[], sessionId?: string}
    Omit sessionId to start a new conversation. imageIds come from POST /upload and are single-use; text may be empty when images are attached.
  {"type":"cancel", sessionId: string}
    Abort the turn in flight.
  {"type":"resume", sessionId: string, lastSeq: number}
    Replay everything you missed.
  {"type":"ping", t?: number}
    Round-trip check; answered with pong.

Receive:
  ready
    Sent on connect: your identity, session id, tool list, limits.
  turn.start
    A turn began. Carries turnId, text, speaker, and images (a count) when pictures were attached.
  step.start
    One model call begins.
  text.delta
    Reply text, token by token. Concatenate in order.
  text.done
    final=false means that text was narration; final=true means it is the answer.
  tool.call
    A tool started. callId correlates with tool.result.
  tool.result
    That tool finished: ok, durationMs, result.
  step.end
    Model call finished, with duration and tool-call count.
  turn.end
    Turn complete, with the full reply text.
  turn.error
    Turn failed.
  turn.queued
    Another turn is ahead of yours on this session.
  notice
    Out-of-band info/warn/error.
  pong
    Reply to ping.

## Rules a client must follow
- IGNORE message types you do not recognise. New ones get added without a
  protocol bump.
- Concatenate text.delta in arrival order to build the reply. text.done or
  turn.end give you the authoritative full text if you miss any.
- Every event carries turnId. Tool events also carry callId, so a tool.result
  can be matched to its tool.call even when the same tool runs twice in a step.
- seq is monotonic per session. Track the last one you saw and send it with
  "resume" after a reconnect.

## Example
  curl -H "Authorization: Bearer $TOKEN" http://mateusz-desktop.tail96606f.ts.net/status