Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 28 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,18 @@ This file is the canonical source for unreleased changes and published release n
- Prompts queued while the agent works can be read and changed before it takes them in. `Control.pending` lists them, steers and follow-ups, in the order they were sent. `Control.cancel` withdraws one, recorded as a `session.prompt.cancelled` event; it returns `false` when the prompt was already taken in, and a cancelled message id may be sent again. `Control.update` moves one to the other lane or rewrites its text, keeping its place, recorded as a `session.prompt.updated` event; moving it to the steer lane also wakes the session, so a prompt left queued by a stop runs now.
- Tools declare an `exposure`. Only `"direct"` and `"model"` tools reach the request, the `<tools>` list and the tool rules, and only they run; a call to any other tool gets `Unknown tool: <name>`. The bash file-ops rule and the skills hint name only declared tools, and `<skills>` is left out when neither `read` nor `bash` is declared. A plugin registering an unknown exposure fails in its `setup`.
- `read` tells a model without image input that the image it read is left out of the request: `[Current model does not support images. The image will be omitted from this request.]` is added to its note.
- A run cut off by a crash or a shutdown resumes when the server starts again (`Control.resumeUnfinished`). A crash counts as a restart and a shutdown does not; a committed turn starts the count over. After 5 restarts (`Control.RESTART_LIMIT`) the session is parked instead of resumed: `Session.Info.parked` is `true`, and its next prompt runs it again. A resumed run answers the reply it was cut off in before a queued follow-up goes in; steers join it at once. A run the user stopped is not resumed, and what was queued behind it stays queued.
- A run cut off by a crash or a shutdown resumes when the server starts again (`Control.resumeUnfinished`). A crash counts as a restart and a shutdown does not; a committed turn starts the count over. After 5 restarts (`Control.RESTART_LIMIT`) the thread is parked instead of resumed: `Session.ThreadInfo.parked` is `true`, and its next prompt runs it again. A resumed run answers the reply it was cut off in before a queued follow-up goes in; steers join it at once. A run the user stopped is not resumed, and what was queued behind it stays queued.

- `Session.ThreadInfo.usage`: the billed cost and tokens of the thread's own entries, without what it inherits from the thread it was forked from.

#### Breaking Changes

- A session is a container of threads: one event log and one default place to run, holding a `main` thread created with it and the threads forked from it. A thread is a linear transcript; `fork` at or before a committed entry is the only way to branch. Branch, clone, leaf and `parentId` are gone.
- `Session.create` returns a session handle with `main`, `thread(id | "main")` and `threads`. Prompting, running, waiting, resuming, interrupting, configuring, forking, events and history (was `path()`) are on thread handles. `Session.attach` returns a thread handle, `main` when `threadId` is absent. `Session.relink` with `threadId` moves only that thread.
- Title, model, thinking level, usage, execution and `parked` belong to a thread (`Session.ThreadInfo`). `Session.Info` has none of them and gains `mainThreadId`. A thread is titled by its first own prompt; a fork has no title until then.
- `Control` addresses threads: `prompt` and `run` take an optional `threadId` (absent = `main`); `wait`, `resume`, `interrupt`, `pending`, `cancel` and `update` take a thread id. `interruptSession` stops every thread of a session.
- Events: every thread-scoped event carries `threadId`. `session.created`, `session.thread.forked` and `session.thread.configured` are new; `session.thread.configured` replaces `session.config.changed`, and `session.next.forked` is removed. Entry types `configChange` and `branchSummary` are removed.
- Storage starts over with a single new migration; databases from earlier versions are not carried forward.

#### Fixed

Expand All @@ -38,10 +49,21 @@ This file is the canonical source for unreleased changes and published release n

#### Added

- Added the `session.queue` RPC (`{ sessionId }`): the prompts sent while the agent works and not yet taken in, steers and follow-ups, in the order they were sent.
- Added the `session.cancel` RPC (`{ sessionId, messageId }`), which withdraws a queued prompt. `cancelled` is `false` when the prompt was already taken in.
- Added the `session.update` RPC (`{ sessionId, messageId, delivery?, text? }`), which moves a queued prompt to the other lane or rewrites its text, keeping its place. `delivery: "steer"` also wakes the session. `updated` is `false` when the prompt was already taken in.
- `codework serve` resumes the sessions a crash or a shutdown cut off when it starts. Session info carries `parked: true` for a session that restarted too often to resume on its own; its next prompt runs it again.
- Added the `thread.queue` RPC (`{ sessionId, threadId? }`): the prompts sent while the agent works and not yet taken in, steers and follow-ups, in the order they were sent.
- Added the `thread.cancel` RPC (`{ sessionId, threadId?, messageId }`), which withdraws a queued prompt. `cancelled` is `false` when the prompt was already taken in.
- Added the `thread.update` RPC (`{ sessionId, threadId?, messageId, delivery?, text? }`), which moves a queued prompt to the other lane or rewrites its text, keeping its place. `delivery: "steer"` also wakes the thread. `updated` is `false` when the prompt was already taken in.
- `codework serve` resumes the sessions a crash or a shutdown cut off when it starts. Thread info carries `parked: true` for a thread that restarted too often to resume on its own; its next prompt runs it again.

- `codework run --thread <id|main>` continues one thread of `--session`.
- `codework thread list <session>` lists a session's threads with their model, usage and title. `codework thread fork <session> --at <entry>` or `--before <entry>` starts a new thread and prints its id, then for `--before` the text of the prompt it left out. `codework session relink <session> --thread <id|main>` moves one thread to another checkout. All three take `--json`.
- `ThreadInfo.usage` reports a thread's own cost and tokens. `event.subscribe` and `session.log` take `threadId` to keep only that thread's events.
- ACP: every thread of a session is an ACP session of its own, so forks can be listed, loaded and prompted; the main thread keeps the session's id. `session/fork` starts a new thread from the last committed entry.

#### Breaking Changes

- The RPC is split by what it addresses. `session.*` keeps `create`, `link`, `relink`, `delete`, `interrupt` (every thread) and `log`. `list`, `info`, `history`, `queue`, `configure`, `prompt`, `cancel`, `update`, `interrupt`, `message` and `wait` move to `thread.*`, with `fork` new there; they take `{ sessionId, threadId? }`, and an absent `threadId` means the session's `main` thread.
- `session.create` and `session.relink` return the addressed thread's `ThreadInfo`, with its session embedded. `SessionInfo` has no title, model, thinking level or `parked`, and gains `mainThreadId`.
- ACP `session/cancel` stops only the thread its session names, not every thread of the CodeWork session.

#### Fixed

Expand Down Expand Up @@ -93,6 +115,7 @@ This file is the canonical source for unreleased changes and published release n
#### Added

- `ToolCallContext.modelInput`: the input modalities of the model the tool call answers, such as `["text"]` or `["text", "image"]`. It is optional, and tool hooks receive it too.
- `ThreadID` in `@codeworksh/plugin/ids`, and `threadId` next to `sessionId` on the plugin context and the tool hooks: the thread the call belongs to.
- `exposure` on tool definitions: `"direct"` (default), `"model"`, `"codemode"`, `"deferred"` or `"hidden"`, as the `ToolExposure` schema. `declared(def)` is true for `"direct"` and `"model"`, the tools declared to the model.

## [@codeworksh/cli@0.4.0] - 2026-10-20
Expand Down
29 changes: 27 additions & 2 deletions packages/codework/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,12 @@ codework run "Inspect and fix the failing tests"
# Create a session with explicit provider and model
codework run --provider openai --model gpt-5.5 --thinking high "Plan database migration"

# Continue an existing session
# Continue an existing session (its main thread)
codework run --session ses_01a070f0 "Now implement the migration script"

# Continue one of its threads
codework run --session ses_01a070f0 --thread thr_01a071c2 "Try it without the cache"

# Run in an isolated sandbox (local, daytona, vercel, memory, sqldb)
codework run --sandbox-driver daytona "Inspect repository"
codework run --sandbox-driver daytona --sandbox-provider-id <remote-id> "Continue in sandbox"
Expand All @@ -51,6 +54,7 @@ codework run --sandbox-driver daytona --sandbox-provider-id <remote-id> "Continu

- `--server <url>` — Connect to a running RPC server, e.g. `ws://127.0.0.1:7433/rpc/v1`.
- `-s, --session <id>` — Continue an existing session.
- `--thread <id>` — Thread of `--session` to continue: a thread ID, or `main` (default).
- `-C, --cwd <path>` — Working directory for a new session.
- `--sandbox-driver <driver>` — Sandbox driver (`local`, `daytona`, `vercel`, `memory`, `sqldb`). Default: `local`.
- `--sandbox-id <id>` — Reuse an existing sandbox instance; mutually exclusive with driver/provider coordinates.
Expand All @@ -63,6 +67,27 @@ Global flags: `--user-config-dir`, `--home`, `--database`.

---

### `codework thread`

A session holds one or more threads: its `main` thread, and the forks made from it. These commands talk to a running server (`--server`, default `http://127.0.0.1:7433`).

```bash
# List a session's threads with their model and usage
codework thread list ses_01a070f0

# Start a new thread through an entry, or just before a prompt to send it again
codework thread fork ses_01a070f0 --at <entry-id>
codework thread fork ses_01a070f0 --thread thr_01a071c2 --before <entry-id>

# Move one thread into another checkout of the project, keeping its position under it;
# the rest of the session stays where it is
codework session relink ses_01a070f0 --thread thr_01a071c2 -C ~/work/api
```

`thread fork` prints the new thread ID, then for `--before` the text of the prompt it left out. `--json` prints the wire form.

---

### `codework serve`

Start a persistent server that owns sessions and sandboxes:
Expand All @@ -76,7 +101,7 @@ codework run --server ws://127.0.0.1:7433/rpc/v1 --sandbox-id <sandbox-id> "Star

The default address is `127.0.0.1:7433`; `--port 0` picks an available port and prints the actual URL. Set `--home`, `--database`, and `--user-config-dir` on the server. Model credentials, plugins, and working directories are resolved by the server. A remote run does not boot a local harness.

Events are live and not replayed. The client subscribes before admitting its prompt and waits for execution completion after rendering. Lost connections and overflow fail the command; disconnecting leaves server work running. Ctrl-C sends `session.interrupt`, which interrupts the shared session. Remote runs print the sandbox ID for reuse. `session.interrupt` returns `{ interrupted }` as soon as the stop is accepted; `session.wait` is the separate cleanup barrier. A busy period reports itself as `session.execution.started` followed by exactly one of `succeeded`, `failed`, or `interrupted` -- a failure carries a category (`provider-authentication-error`, `model-not-found-error`, `sandbox-mount-error`, ...) that the client renders, and an interruption carries whether it was the user or a server shutdown. Managed sandboxes remain available until explicitly stopped or server shutdown; external sandboxes are not stopped.
Events are live and not replayed. The client subscribes before admitting its prompt and waits for execution completion after rendering. Lost connections and overflow fail the command; disconnecting leaves server work running. Ctrl-C sends `thread.interrupt`, which stops the thread the run prompted. Remote runs print the sandbox ID for reuse. `thread.interrupt` returns `{ interrupted }` as soon as the stop is accepted; `thread.wait` is the separate cleanup barrier, and `session.interrupt` stops every thread of a session. A busy period reports itself as `session.execution.started` followed by exactly one of `succeeded`, `failed`, or `interrupted` -- a failure carries a category (`provider-authentication-error`, `model-not-found-error`, `sandbox-mount-error`, ...) that the client renders, and an interruption carries whether it was the user or a server shutdown. Managed sandboxes remain available until explicitly stopped or server shutdown; external sandboxes are not stopped.

The v0 endpoint has no authentication; its default binding is loopback. Plugins publish their own event types by declaring them (`Plugin.define({ events: [...] })`, namespaced `plugin.<plugin-id>.*`); the feed carries those and skips types nothing declared. Invalid payloads for declared types fail with a typed encoding error.

Expand Down
2 changes: 2 additions & 0 deletions packages/codework/src/acp/agent.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ export interface Handlers {
/** Must replay the session's history through `Client.sessionUpdate` before it returns. */
readonly loadSession: Handler<Acp.LoadSessionRequest, Acp.LoadSessionResponse>;
readonly listSessions: Handler<Acp.ListSessionsRequest, Acp.ListSessionsResponse>;
readonly forkSession: Handler<Acp.ForkSessionRequest, Acp.ForkSessionResponse>;
readonly setConfigOption: Handler<Acp.SetSessionConfigOptionRequest, Acp.SetSessionConfigOptionResponse>;
readonly prompt: Handler<Acp.PromptRequest, Acp.PromptResponse>;
readonly cancel: (notification: Acp.CancelNotification) => Effect.Effect<void>;
Expand Down Expand Up @@ -81,6 +82,7 @@ export const serve = Effect.fn("ACP.serve")(function* (
.onRequest("session/new", handle(handlers.newSession))
.onRequest("session/load", handle(handlers.loadSession))
.onRequest("session/list", handle(handlers.listSessions))
.onRequest("session/fork", handle(handlers.forkSession))
.onRequest("session/set_config_option", handle(handlers.setConfigOption))
.onRequest("session/prompt", handle(handlers.prompt))
.onNotification("session/cancel", handle(handlers.cancel))
Expand Down
Loading
Loading