@theokit/acp 3.0.2 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,174 @@
 # Changelog
 
+## 4.0.0
+
+### Major Changes
+
+- 2c33d98: `AcpServerOptions.info` is now advertised in the `initialize` handshake, and two inert capability
+  fields are removed.
+
+  `info` was accepted, typed, and documented as advertised — and read by nothing. It is now sent as
+  `InitializeResponse.agentInfo`, the protocol slot that matches its shape. It is omitted when you do
+  not supply one: defaulting to this package's own metadata would label every agent as the adapter
+  serving it, and a name that is confidently wrong is worse for a host to display than one that is
+  absent.
+
+  **Breaking:** `AcpCapabilities.forkSession` and `AcpCapabilities.listSessions` are removed.
+  `AgentCapabilities` has no slot for either at `@agentclientprotocol/sdk@0.22.1` — neither name
+  appears in its schema — and neither gated anything: `session/fork` is refused unconditionally and
+  `session/list` is answered regardless. Setting them never did anything; removing them says so at
+  compile time.
+
+### Minor Changes
+
+- 92a9d6a: `InvalidAgentError` is now exported from `@theokit/acp`.
+
+  It is the single startup failure of `serveAcp` and its documented name, but it was not on the
+  package's public surface, so a consumer could neither `import` it nor `instanceof` it — leaving
+  `err.name` string-matching as the only way to tell a bad `agent` from any other rejection. The
+  package's other named error, `PromptTooLargeError`, was already exported "so that text has a named
+  origin"; both have the same justification.
+
+### Patch Changes
+
+- 2ba468b: `session/cancel` no longer kills the session.
+
+  The session owned exactly one `AbortController`, created at session creation and never replaced, so
+  cancelling one turn handed every later prompt on that session an already-aborted signal. ACP hosts
+  routinely cancel a turn and then prompt again: the agent silently stopped answering while the host
+  stayed connected and the session stayed listed.
+
+  The abort scope is now armed per turn, which is what `session/cancel` means — the host stops the
+  answer being written, not the conversation. Cancelling the turn in flight still works.
+
+- e3f2a82: Public-API documentation reviewed file by file, and corrected wherever it disagreed
+  with the code. The docblocks ship in the `.d.ts`, so these read as behaviour changes
+  in an editor even though no behaviour changed.
+
+  The corrections that change what a caller would do:
+
+  - **`sdk-cache` documented its own premise backwards.** The header example labelled a
+    semantic hit as if it avoided the provider call. `asPlugin()` returns the cached
+    answer as `recalledContext`, which the agent loop injects as a `<memory-context>`
+    block _before_ the prompt — the request still goes to the provider. The two modes
+    are now labelled separately, with a table saying which one short-circuits and which
+    one seeds.
+  - **`sdk-handoff`'s five error classes said "throw".** Under the plugin wiring the
+    handler never throws; every failure becomes a tool result `{"ok":false,…}` handed
+    back to the model. Each class now says where it is actually observable. The header
+    also told readers to `import { Handoff } from "@theokit/sdk"`, from which it was
+    extracted.
+  - **`sdk-budget`'s `charge()` claimed idempotency across concurrent calls.** The mutex
+    serialises, it does not deduplicate: two identical calls record twice. Related, and
+    newly documented: with `maxUsd` set, a model missing from the pricing table denies
+    every request rather than passing it — and the table matches by exact string, so
+    `"openai/gpt-4o"` does not match `"gpt-4o"`.
+  - **The three `memory-*` adapters advertised an env-var fallback they do not read**,
+    and their peer dependencies are required rather than optional. Their behavioural
+    differences are now stated where they break the "interchangeable adapter"
+    assumption — honcho ignores `k` and always throws on `delete`; mem0 recalls across
+    sessions by design; supermemory ignores `sessionId` entirely.
+  - **`sdk-memory`'s `truncated` flag was documented as its own inverse**, and its
+    dreaming sweep claimed a mutex it never takes against the writer it names.
+  - **`sdk-tools`** corrected `run_vitest`'s unreachable `no_vitest` code, `truncation`'s
+    replacement-character claim, and two return shapes missing a live error code.
+  - **`acp`/`cli`** corrected sixteen statements including a named error class that is
+    not the one raised, a handler documented as calling `fork()` that refuses
+    unconditionally, handlers described as pure that mint ids and mutate a store, a
+    config loader credited to Zod in a package that does not import it, and a `--force`
+    scaffold described as atomic that deletes the destination before the rename.
+
+  Undocumented public symbols were documented across every package, with each claim
+  checked against the implementation rather than inferred from the name.
+
+- e368fc1: Every published declaration file now compiles without `skipLibCheck` (#345). The
+  DTS rollup emitted symbols as a re-export from a chunk while omitting them from
+  that chunk's `import`, and dropped type-only imports from external packages —
+  leaving 51 unresolved references across ten of the twelve packages. Nothing broke
+  at runtime, and `tsc` stayed green for anyone with `skipLibCheck` on, but a
+  consumer running type-aware lint saw every type reached through one degrade to
+  `error`.
+
+  The declarations are repaired at build time from the compiler's own diagnostics.
+  No source or API change.
+
+- 29ebaa1: Three places where a value was reported that nobody had actually selected.
+
+  **An empty `POSTHOG_API_KEY` no longer masks a valid `POSTHOG_PROJECT_API_KEY`.** The adapter read
+  `POSTHOG_API_KEY ?? POSTHOG_PROJECT_API_KEY`, and `??` treats `""` as present. Leaving a variable
+  blank in a `.env` or a CI config is the ordinary way to say "unset", so a blank primary key silently
+  disabled telemetry while a working key sat in the sibling variable — and telemetry going quiet is the
+  one failure that reports itself as nothing at all. Empty and whitespace-only values now fall through.
+  The same trap on `POSTHOG_HOST` is closed with it.
+
+  **The provider inspector reports the model the route resolves to.** `extractModelName` documented
+  itself as surfacing the name from the prefix split and instead returned a hard-coded default, so a
+  route configured as `anthropic:claude-opus-4` with no explicit `route.model` reported
+  `claude-3-7-sonnet`. That field exists to let a caller confirm which model a route resolves to; a
+  wrong answer there is worse than no answer, because it is indistinguishable from a right one. The
+  name is now derived from the model id the route actually carries, and the default-model lookup that
+  produced the literal is deleted rather than left as a decoy.
+
+  **An errored ACP run no longer reaches the client as `end_turn`.** The stop-reason mapping fell
+  through to `end_turn` for any run status it did not recognise, so a failure was reported over the
+  wire as an ordinary completed turn — invisible to every ACP client, which is the swallowed-error
+  shape the project's error-handling rules forbid by name. The protocol's `StopReason` has no error
+  value, so an unmapped status now surfaces through the JSON-RPC error channel the handler already uses
+  for every other failure, with a message naming the status that was not mapped. A dead branch
+  returning `end_turn` twice is removed in the same pass.
+
+- 1ac974f: **`@theokit/sdk-pty` declares its licence.** Every published version up to now shipped with no `license` field in the manifest. npm reads the field, not the directory, so the tarball was all-rights-reserved to whoever installed it — the terms were sitting in the `LICENSE` file it already shipped, saying nothing. The field now says `Apache-2.0`, which is what that file has always been and what all eleven sibling packages declare.
+
+  **Four packages now ship the licence they declare.** `@theokit/cli`, `@theokit/memory-honcho`, `@theokit/memory-mem0` and `@theokit/memory-supermemory` declared `Apache-2.0` and listed `LICENSE` in `files`, and no such file existed. npm omits a declared-but-absent path in silence, so every published tarball asserted the licence while carrying none of its terms — and §4(a) requires a copy to travel with the distribution. The file is there now, byte-identical to the one the other packages ship.
+
+  **Six packages complete the rest of their published metadata.** Each field is here for what its absence costs a consumer:
+
+  - `homepage` and `bugs` — the npm page renders both; without them someone who hits a defect has no route back to the project.
+  - `engines.node` — npm warns on an unsupported runtime only when the range is declared. `@theokit/sdk-pty` declared none, so a Node 18 install failed later and somewhere unrelated.
+  - `sideEffects` — a bundler keeps every module of a package that stays silent. Declared only after checking: a clean scan of each built ESM entry found zero top-level statements, the residual hits being closing tokens of declarations. `@theokit/sdk` keeps its path-array form, which is the honest shape for a package whose agent entry registers on import.
+  - `publishConfig.access` — a scoped package defaults to `restricted`. Three declared none and reached npm public only because the release flow supplied the flag; the manifest states it now instead of depending on how it is invoked.
+  - `@theokit/sdk-pty` also ships its `CHANGELOG.md`, which existed on disk and was absent from `files`.
+
+  The gate that should have caught any of this covered three packages out of twelve, by way of a hand-written list. It now derives the list from `packages/`, asserts the whole contract, and fails when the sweep discovers nothing rather than passing by having nothing to check.
+
+- e699569: **The repository moved to the official `usetheokit` organization.** Every `repository`, `bugs` and `homepage` field now points there, along with the README, `CONTRIBUTING.md`, `SECURITY.md` and the issue templates. Existing clones and any URL already published keep working — GitHub redirects a transferred repository permanently — so this is a correctness fix for the metadata npm renders, not a break.
+
+  **The Apache-2.0 text every package ships was replaced with the official one.** The copy distributed until now had paragraph 4(d) truncated: it read "except as required for describing the origin of the Work and reproducing the content of the NOTICE file", dropping "reasonable and customary use" from the licensed clause. §4(d) governs what a redistributor must do with attribution notices, and the omission narrowed it.
+
+  That matters more than a typo would. The manifests declare the SPDX identifier `Apache-2.0`, which is an assertion that the terms are _the_ Apache-2.0 terms — a licence scanner resolves the identifier and never reads the file. A consumer's compliance review, which does read the file, would find a body that no longer matches the identifier and has no name of its own. Every `LICENSE` in this repository is now byte-identical to the canonical text, with the appendix filled in.
+
+  Nothing else about the terms changed: the licence is the same licence it has always been meant to be, and no package changes what it grants.
+
+- f692988: The reference docs no longer ship inside the package. `node_modules/@theokit/sdk/docs/` is gone, along with the `harness-capability-map.md` and `error-codes.md` files it carried — the `docs` entry was removed from the published `files` list and the build step that generated it was removed with it.
+
+  The exported TypeScript types are now the only reference surface, and they remain the canonical contract: every public primitive carries its import path, signature and JSDoc example, surfaced by your editor. Nothing about the runtime API changed.
+
+  The scaffolded agent context still ships, unchanged, under `claude-template/`.
+
+- c7385d2: Test runs no longer claim every core on the host.
+
+  None of the package configs capped `maxWorkers`, so vitest's default applied: `os.availableParallelism()`,
+  one fork per core, each booting a full test environment. The repo's `test` script is
+  `turbo run test --filter='./packages/*'`, so that default is paid once per package _concurrently_ —
+  nproc forks times turbo's concurrency, on nproc cores. Measured on a 12-thread machine during an
+  unrelated investigation, two vitest pools alone were enough to reach load average 33.89 with the
+  desktop unusable; a full fan-out is several times that.
+
+  `@theokit/sdk` is the interesting case. B-104 recorded on 2026-08-19 that the `poolOptions.forks.*`
+  block was 100% dead in Vitest 4, deleted it, and noted that `fileParallelism: false` was forcing
+  `maxWorkers` to 1 unconditionally, so a fork-count knob could not act. B-059 then flipped
+  `fileParallelism` to `true` on 2026-08-20, which made the knob able to act again — and nothing
+  reintroduced one, so the package silently went back to the uncapped default. That comment has been
+  corrected along with the config; it claimed no knob existed, which is no longer true.
+
+  The cap leaves 4 cores free (`Math.max(2, cpus().length - 4)`), scaling with the runner rather than
+  hard-coding one machine's core count. It costs no wall-clock: measured in `theokit-ui`, the full
+  suite ran 73.96s at 4 workers against 74.36s at 12, so the parallelism above the cap was already
+  noise. Verified as resolved config rather than as file contents — `createVitest` reports
+  `maxWorkers: 8` on a 12-thread host, which is the formula, not the default.
+
+  This changes no published behaviour; it is test tooling only. Refs usetheokit/theokit-ui#51.
+
 ## 3.0.2
 
 ### Patch Changes

package/LICENSE

@@ -137,8 +137,8 @@
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each

package/README.md

@@ -2,7 +2,7 @@
 
 Agent Client Protocol (ACP) server adapter for [`@theokit/sdk`](https://www.npmjs.com/package/@theokit/sdk).
 
-Exposes a `SDKAgent` over stdio JSON-RPC so [Zed](https://zed.dev), Cursor, Claude Desktop, and any [ACP-compatible host](https://agentclientprotocol.com) can drive it as a coding agent — without writing any glue code.
+Exposes a `SDKAgent` over stdio JSON-RPC so any [ACP-compatible host](https://agentclientprotocol.com) can drive it as a coding agent — without writing any glue code.
 
 ```bash
 npm i @theokit/acp @theokit/sdk @agentclientprotocol/sdk
@@ -25,7 +25,7 @@ export default async (sessionId: string) => {
 ```
 
 ```bash
-# Launch the server (Zed/Cursor will do this for you)
+# Launch the server (an ACP host will do this for you)
 npx theokit-acp --entry ./my-agent.ts
 ```
 
@@ -66,6 +66,19 @@ await serveAcp({
 
 Pre-1.0 (`0.x`). Breaking changes are allowed within `0.x` (D181 pattern) until upstream ACP stabilizes.
 
+## API reference
+
+Every symbol this package exports, with the exact specifier to import it from, is in the generated
+capability map that ships inside `@theokit/sdk`:
+
+```
+node_modules/@theokit/sdk/docs/harness-capability-map.md   # symbol -> import specifier
+node_modules/@theokit/sdk/docs/error-codes.md              # every `code` an error can carry
+```
+
+Both are generated from the built type declarations, so they describe the version you installed
+rather than the version someone wrote a page about.
+
 ## License
 
 Apache-2.0

package/dist/index.cjs

@@ -30,8 +30,6 @@ function _interopNamespace(e) {
 var acp2__namespace = /*#__PURE__*/_interopNamespace(acp2);
 var path__default = /*#__PURE__*/_interopDefault(path);
 
-// src/serve.ts
-
 // src/agent-resolver.ts
 function looksLikeSDKAgent(value) {
   return typeof value === "object" && value !== null && typeof value.agentId === "string" && typeof value.send === "function";
@@ -73,6 +71,7 @@ function buildInitializeResponse(_params, deps) {
         embeddedContext: userCaps.prompt?.embeddedContext ?? true
       }
     },
+    ...deps.info !== void 0 ? { agentInfo: { ...deps.info } } : {},
     authMethods: []
   };
 }
@@ -485,6 +484,39 @@ function extractPrompt(blocks, maxBytes) {
   return { text: state.textParts.join("\n"), attachments: state.attachments };
 }
 
+// src/session-store.ts
+function armTurn(session) {
+  session.abortController = new AbortController();
+  return session.abortController.signal;
+}
+var SessionStore = class {
+  map = /* @__PURE__ */ new Map();
+  /** @throws Error on a duplicate id — the caller must have checked `has` first. */
+  create(session) {
+    if (this.map.has(session.sessionId)) {
+      throw new Error(`duplicate sessionId: ${session.sessionId}`);
+    }
+    this.map.set(session.sessionId, session);
+  }
+  get(sessionId) {
+    return this.map.get(sessionId);
+  }
+  /** `true` when an entry was removed. Does NOT dispose the agent or abort its controller. */
+  delete(sessionId) {
+    return this.map.delete(sessionId);
+  }
+  /** A new array over the live session objects — the array is a copy, the sessions are not. */
+  list() {
+    return [...this.map.values()];
+  }
+  size() {
+    return this.map.size;
+  }
+  has(sessionId) {
+    return this.map.has(sessionId);
+  }
+};
+
 // src/prompt-handler.ts
 function mapStopReason(runStatus, errorCode) {
   if (errorCode === "aborted" || runStatus === "cancelled") return "cancelled";
@@ -492,8 +524,16 @@ function mapStopReason(runStatus, errorCode) {
   if (errorCode === "context_length_exceeded" || errorCode === "max_tokens") return "max_tokens";
   if (errorCode === "max_iterations") return "max_turn_requests";
   if (runStatus === "finished") return "end_turn";
-  return "end_turn";
+  return void 0;
 }
+var UnmappedRunStatusError = class extends Error {
+  constructor(runStatus, errorCode, detail) {
+    super(
+      `run ended in status "${runStatus}" with unmapped error code "${errorCode}"${detail !== void 0 ? `: ${detail}` : ""}`
+    );
+    this.name = "UnmappedRunStatusError";
+  }
+};
 function isAbortError(err) {
   if (!(err instanceof Error)) return false;
   return err.name === "AbortError" || err.message.includes("aborted");
@@ -512,13 +552,14 @@ function extractOrError(params, deps) {
   }
 }
 async function runPrompt(session, text, params, deps) {
-  const run = await session.agent.send(text, { signal: session.abortController.signal });
+  const signal = armTurn(session);
+  const run = await session.agent.send(text, { signal });
   try {
     await translateStream({
       messages: run.stream(),
       conn: deps.conn,
       sessionId: params.sessionId,
-      signal: session.abortController.signal,
+      signal,
       log: deps.log
     });
   } catch (err) {
@@ -527,7 +568,11 @@ async function runPrompt(session, text, params, deps) {
   }
   const result = await run.wait();
   const errorCode = result.status === "error" && result.error !== void 0 ? result.error.code ?? "" : "";
-  return mapStopReason(result.status, errorCode);
+  const stopReason = mapStopReason(result.status, errorCode);
+  if (stopReason === void 0) {
+    throw new UnmappedRunStatusError(result.status, errorCode, result.error?.message);
+  }
+  return stopReason;
 }
 async function installPermissionOrError(session, params, deps) {
   if (deps.permissionMode === "auto") return void 0;
@@ -563,37 +608,12 @@ async function handlePrompt(params, deps) {
   } catch (err) {
     if (isAbortError(err)) return { response: { stopReason: "cancelled" } };
     const msg = err instanceof Error ? err.message : String(err);
-    deps.log(`[acp] agent.send threw: ${msg}`);
+    const label = err instanceof UnmappedRunStatusError ? "run ended unmapped" : "agent.send threw";
+    deps.log(`[acp] ${label}: ${msg}`);
     return { error: { code: ACP_ERR.INTERNAL_ERROR, message: msg } };
   }
 }
 
-// src/session-store.ts
-var SessionStore = class {
-  map = /* @__PURE__ */ new Map();
-  create(session) {
-    if (this.map.has(session.sessionId)) {
-      throw new Error(`duplicate sessionId: ${session.sessionId}`);
-    }
-    this.map.set(session.sessionId, session);
-  }
-  get(sessionId) {
-    return this.map.get(sessionId);
-  }
-  delete(sessionId) {
-    return this.map.delete(sessionId);
-  }
-  list() {
-    return [...this.map.values()];
-  }
-  size() {
-    return this.map.size;
-  }
-  has(sessionId) {
-    return this.map.has(sessionId);
-  }
-};
-
 // src/serve.ts
 var DEFAULT_MAX_PROMPT_BYTES = 2 * 1024 * 1024;
 var DEFAULT_PERMISSION_TIMEOUT_MS = 6e4;
@@ -626,7 +646,10 @@ async function serveAcp(options) {
   });
   new acp2__namespace.AgentSideConnection((conn) => {
     return {
-      initialize: async (params) => buildInitializeResponse(params, { capabilities: options.capabilities }),
+      initialize: async (params) => buildInitializeResponse(params, {
+        capabilities: options.capabilities,
+        ...options.info !== void 0 ? { info: options.info } : {}
+      }),
       authenticate: async (_params) => {
         return {};
       },
@@ -687,6 +710,7 @@ async function serveAcp(options) {
   );
 }
 
+exports.InvalidAgentError = InvalidAgentError;
 exports.PromptTooLargeError = PromptTooLargeError;
 exports.serveAcp = serveAcp;
 //# sourceMappingURL=index.cjs.map