agentSessions

The agentSessions namespace: 4 functions.

agentSessions/forget

agentSessions.forget(worldGuid, slot)

Drop this machine's record for (world, dock slot), so the next launch of that slot starts a fresh conversation instead of resuming. Succeeds whether or not a record was there. The claude transcript itself stays on disk. Editor profile only.

Parameters

• worldGuid string — Guid of the world the agent belongs to
• slot number — Agent dock slot, a positive integer

agentSessions/get

agentSessions.get(worldGuid, slot) -> {sessionId, name, workspace, lastSpawn, harness} | nil

The conversation this machine recorded for (world, dock slot), or nil when there is none: its id, display name, working directory, last launch, and the harness that runs it (claude, codex, cursor, or a DotBot agent such as dotbot-claude; empty on a record from before the harness was recorded, which Claude Code ran). Only meaningful on the machine holding the transcript; another computer has its own conversations for the same world. Editor profile only.

Parameters

• worldGuid string — Guid of the world the agent belongs to
• slot number — Agent dock slot, a positive integer

Returns { sessionId: string, name: string, workspace: string, lastSpawn: string, harness: string }? — The recorded session, or nil

agentSessions/put

agentSessions.put(worldGuid, slot, {sessionId, name, workspace, harness})

Record the conversation now occupying (world, dock slot): a Claude Code session id, a Codex thread id, or a DotBot conversation address (<agent>/<conversation id>), replacing whatever this machine held for that slot. The engine stamps lastSpawn with the current UTC time, so the caller supplies only the session id, its display name, the directory it runs in, and the harness that runs it. A later agentSessions.get on this machine returns what was written here. The same record is kept as the run of this engine's seat, so a report on this engine names the conversation its own agent runs while another engine on the world runs one in the same slot. Called on every spawn of a slot's agent, a reopened conversation included. Editor profile only.

Parameters

• worldGuid string — Guid of the world the agent belongs to
• slot number — Agent dock slot, a positive integer
• record table — {sessionId: string, name: string?, workspace: string?, harness: string?} - sessionId is required

agentSessions/record

agentSessions.record(sessionId?, entry)

Record one entry of a run the engine hosts itself (a DotBot run, which has no CLI to keep a transcript of its own): appended, with ts_ms set to the time it was recorded, as one JSON line of the transcript of sessionId at <config dir>/agent-transcripts/<sessionId>.jsonl, which agent_run_report reads. Every entry also becomes the in-engine agent's state in the engine's status (GET /engine/status, agent.run), so an entry with no sessionId (a run refused before it had a conversation) is reported there and written nowhere. An entry is at most 1 MiB of JSON and a transcript at most 256 MiB. Editor profile only.

Parameters

• sessionId string? — The conversation the entry belongs to, or nil for an entry about the run as a whole
• entry table — A table with a string type, written as JSON