@theokit/sdk 5.12.1 → 5.14.0

package/dist/{inject-session-JVTZNQF6.cjs → inject-session-3ICZIJ2N.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkYOVZMN4P_cjs = require('./chunk-YOVZMN4P.cjs');
+var chunkLXG6VL6R_cjs = require('./chunk-LXG6VL6R.cjs');
 var chunkYJNYDJ2T_cjs = require('./chunk-YJNYDJ2T.cjs');
 require('./chunk-MSW7LB2V.cjs');
 var chunk3WKWBYPO_cjs = require('./chunk-3WKWBYPO.cjs');
@@ -10,7 +10,7 @@ require('./chunk-RNXXYF22.cjs');
 
 // src/internal/session/inject-session.ts
 async function injectSessionTurn(opts) {
-  await chunkYOVZMN4P_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
+  await chunkLXG6VL6R_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
     const prior = await opts.store.readRecords(opts.loc.agentId);
     const transcript = chunk3WKWBYPO_cjs.SessionTranscript.fromRecords(prior, {
       cwd: opts.loc.cwd,
@@ -25,5 +25,5 @@ async function injectSessionTurn(opts) {
 }
 
 exports.injectSessionTurn = injectSessionTurn;
-//# sourceMappingURL=inject-session-JVTZNQF6.cjs.map
-//# sourceMappingURL=inject-session-JVTZNQF6.cjs.map
+//# sourceMappingURL=inject-session-3ICZIJ2N.cjs.map
+//# sourceMappingURL=inject-session-3ICZIJ2N.cjs.map

package/dist/{inject-session-JVTZNQF6.cjs.map → inject-session-3ICZIJ2N.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-JVTZNQF6.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-3ICZIJ2N.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/{inject-session-THABTKJY.js → inject-session-J26SHHIO.js}

@@ -1,4 +1,4 @@
-import { enqueueSessionWrite } from './chunk-4GUFNDZR.js';
+import { enqueueSessionWrite } from './chunk-3ONIVO2I.js';
 import { invalidateSessionCache } from './chunk-2XC6KDJM.js';
 import './chunk-AGO5S5WD.js';
 import { SessionTranscript } from './chunk-XESYJ4JC.js';
@@ -23,5 +23,5 @@ async function injectSessionTurn(opts) {
 }
 
 export { injectSessionTurn };
-//# sourceMappingURL=inject-session-THABTKJY.js.map
-//# sourceMappingURL=inject-session-THABTKJY.js.map
+//# sourceMappingURL=inject-session-J26SHHIO.js.map
+//# sourceMappingURL=inject-session-J26SHHIO.js.map

package/dist/{inject-session-THABTKJY.js.map → inject-session-J26SHHIO.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-THABTKJY.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-J26SHHIO.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/internal/agent-loop/prune-tool-results.d.ts

@@ -0,0 +1,37 @@
+/**
+ * B-564 — opt-in pruning of aged tool results from the next LLM request.
+ *
+ * The loop resends every tool result of a run on every later call; with
+ * `SendOptions.pruneToolResults` set, results older than `olderThanRounds` tool rounds are
+ * replaced by a short stub in the REQUEST copy only. The transcript the loop keeps, persists and
+ * resumes from is never touched, so a pruned result can always be recovered (plan D1).
+ *
+ * Position among tool-result messages is the round distance: at call n the newest tool-result
+ * message is round n - 1. So no round counter is threaded through the loop. Text-only feedback
+ * messages the loop pushes between rounds carry no `tool_result` part and do not count.
+ *
+ * A pruned part keeps its `toolUseId` and `isError`: every `tool_use` must still have a paired
+ * `tool_result` on both wires, so the result is shortened, never removed.
+ */
+import type { PruneToolResultsOptions } from "../../types/run.js";
+import type { LlmMessage } from "../llm/types.js";
+export type { PruneToolResultsOptions } from "../../types/run.js";
+/**
+ * Build the messages for one LLM request with aged tool results replaced by a stub.
+ *
+ * Each new round stubs one more previously sent result, so on providers that cache message
+ * prefixes the cached prefix ends earlier; that cost was not measured.
+ *
+ * @param messages - The loop transcript. Never mutated.
+ * @param options - Absent means no pruning: the input array itself is returned, so the
+ *   option-off request is byte-identical to the transcript.
+ * @returns A new array when `options` is set; untouched messages are the same objects.
+ */
+export declare function pruneToolResultsForRequest(messages: LlmMessage[], options: PruneToolResultsOptions | undefined): LlmMessage[];
+/**
+ * Fail fast on an option that cannot describe an age in rounds.
+ *
+ * @throws ConfigurationError with code `invalid_prune_tool_results` when `olderThanRounds` is
+ *   not an integer of at least 1.
+ */
+export declare function validatePruneToolResults(options: PruneToolResultsOptions | undefined): void;

package/dist/internal/auth/credential-store.d.ts

@@ -69,7 +69,7 @@ export declare function readStoredOAuth(config: CredentialStoreConfig, env?: Rec
  * file in the same directory with `wx` (O_EXCL), fsync, close, chmod, then `rename` (atomic on POSIX) —
  * so a crash mid-write leaves whatever was there untouched, and a pre-planted symlink cannot capture the
  * key. The api variant persists the unchanged `{provider, api_key}` (back-compat, no `type` key); the
- * oauth variant persists `{type:'oauth', provider, access, refresh, expires, account_id?}`.
+ * oauth variant persists `{type:'oauth', provider, access, refresh, expires, account_id?, id_token?}`.
  */
 export declare function writeCredential(cred: {
     provider: string;

package/dist/internal/auth/types.d.ts

@@ -109,6 +109,8 @@ export interface StoredOAuthCredential {
     /** Epoch ms the access token expires. */
     expires: number;
     account_id?: string;
+    /** The provider's OpenID ID token, when its token endpoint returned one (#821). */
+    id_token?: string;
 }
 /**
  * Whatever the credential file turned out to hold — the two variants are discriminated by `type`.
@@ -137,6 +139,8 @@ export interface OAuthTokens {
     /** Epoch ms the access token expires. */
     expires: number;
     accountId?: string;
+    /** The OpenID ID token, when the token endpoint returned one (#821). */
+    idToken?: string;
 }
 /** Injected HTTP + clock effects — deterministic in tests, real in production. */
 export interface HttpDeps {

package/dist/internal/providers/discovery.d.ts

@@ -3,8 +3,8 @@
  *
  * Scans `~/.theokit/plugins/model-providers/<name>/index.{js,mjs}` and
  * imports each as a Plugin. Plugins with `kind: "model-provider"` register
- * their profile. Errors per plugin are logged + skipped. Idempotent per
- * process.
+ * their profile. Errors per plugin are logged + skipped. Each plugin is
+ * imported at most once per process; the trust gate is read on every call.
  *
  * EC-9: dynamic `import()` in Node 22 needs `file://` URL for absolute
  * paths in ESM contexts. `pathToFileURL` handles both.

package/dist/internal/providers/trust-gate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The trust gate for provider plugins loaded from disk (M47, B-686).
+ *
+ * Provider discovery (`discovery.ts`) reads this list of NAMES; it authorizes only
+ * `~/.theokit/plugins/model-providers/<name>/`, a folder in the operator's own home. Workspace
+ * manifest plugins never consult it: a cloned workspace chooses its folder names, so they are
+ * trusted by realpath in a record of their own (`runtime/plugin-loader/workspace-plugin-trust.ts`),
+ * which shares the fail-closed file reader below. Both are read on every call and never cached, so
+ * an entry the operator adds takes effect on the next `Agent.create` rather than after a restart.
+ *
+ * @internal
+ */
+/** The explicit trust allowlist the human edits (M47). Fail-closed: missing/malformed ⇒ empty. */
+export declare function trustFilePath(): string;
+/**
+ * M47 — the trust gate for the dynamic-import surface. A plugin's entry executes arbitrary code
+ * at import time, so NOTHING is imported unless the human explicitly trusted the name: either in
+ * `~/.theokit/plugins/trusted-providers.json` (a JSON string array — the auditable primary, mirroring the
+ * approved-hooks posture) or the additive `THEOKIT_TRUSTED_PROVIDERS` env (comma-separated convenience).
+ * Fail-closed: a missing or malformed trust file trusts NOTHING (a malformed file WARNs).
+ */
+export declare function readTrustedNames(): Set<string>;
+/** What a trust file holds, as its fail-closed warnings name it. */
+export interface TrustArrayShape {
+    /** What a malformed file leaves untrusted, e.g. "provider plugins". */
+    readonly subject: string;
+    /** What each entry must be, e.g. "plugin-name strings". */
+    readonly entries: string;
+}
+/**
+ * The non-empty strings in a JSON-array trust file. Fail-closed: a missing file is empty, and a
+ * malformed one (not JSON, not an array) is empty with a WARN; non-string entries are discarded
+ * with a WARN.
+ */
+export declare function readTrustArray(path: string, shape: TrustArrayShape): string[];

package/dist/internal/runtime/plugin-loader/manifest-entry-import.d.ts

@@ -0,0 +1,17 @@
+/**
+ * B-686 — import the `entry` of each trusted workspace manifest plugin.
+ *
+ * `PluginsManager` lists a folder under `<cwd>/.theokit/plugins/<folder>/` whose `PLUGIN.md` names an
+ * `entry`; this step decides whether that code runs. The folder's realpath is checked against the
+ * workspace trust record (`workspace-plugin-trust.ts`) before any `import()`, never its name: a
+ * cloned workspace chooses its folder names, so a name in the provider trust list authorizes
+ * nothing here (review round 1, CWE-829). An untrusted folder's code is never evaluated, and it is
+ * diagnosed once per folder per process. A trusted entry whose import throws,
+ * or whose default export is not a general plugin, fails `Agent.create` with a typed error rather
+ * than being skipped: the operator trusted that code, so dropping it silently would hide a bug.
+ *
+ * @internal
+ */
+import type { Plugin } from "../../plugins/types.js";
+import type { ManifestEntryCandidate } from "./plugins-manager.js";
+export declare function importTrustedManifestPlugins(candidates: ReadonlyArray<ManifestEntryCandidate>, trustedFolders: ReadonlySet<string>): Promise<Plugin[]>;

package/dist/internal/runtime/plugin-loader/workspace-plugin-trust.d.ts

@@ -0,0 +1,16 @@
+/**
+ * B-686 — the trust record for workspace manifest plugins.
+ *
+ * A folder under `<cwd>/.theokit/plugins/<folder>/` is code a cloned repository ships, and the
+ * repository chooses the folder's name. So the record is keyed on what the workspace cannot
+ * choose: the folder's absolute realpath, in `~/.theokit/plugins/trusted-workspace-plugins.json`
+ * (a JSON array). It is a record of its own: a name in the provider trust list
+ * (`providers/trust-gate.ts`) authorizes no workspace folder. Read on every call, never cached;
+ * fail-closed like the provider list, whose reader it shares.
+ *
+ * @internal
+ */
+/** Beside the provider trust file, in `~/.theokit/plugins/`. */
+export declare function workspaceTrustRecordPath(): string;
+/** The folder realpaths the operator trusted; a relative entry is discarded with a WARN. */
+export declare function readTrustedWorkspaceFolders(): Set<string>;

package/dist/internal/runtime/skills/binary-on-path.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/skills/discover-skills.d.ts

@@ -13,6 +13,8 @@ export interface Skill {
     source: string;
     category?: string;
     dependencies?: string[];
+    /** `requires-bins` — executables that must be on PATH for the model to be offered this skill. */
+    requiresBins?: string[];
     /** `disable-model-invocation: true` — the model is never told this skill exists. */
     disableModelInvocation?: boolean;
     /** `user-invocable: false` — carried for a host that has a picker; this SDK has no such surface. */

package/dist/internal/structured-output-helpers.d.ts

@@ -1,5 +1,5 @@
 import type { z as ZodNamespace, ZodType } from "zod";
-import type { AgentOptions, CustomTool, LocalOptions, ModelSelection } from "../types/agent.js";
+import type { AgentOptions, BuiltinToolName, CustomTool, LocalOptions, MemorySettings, ModelSelection } from "../types/agent.js";
 import type { ProviderRoutingSettings } from "../types/providers.js";
 /**
  * Load Zod via createRequire (it's an optional peer dep). Throws a typed
@@ -15,7 +15,8 @@ export declare function requireZod(): typeof ZodNamespace;
 export declare function makeOutputTool(jsonSchema: Record<string, unknown>, onCapture: (input: unknown) => string | Promise<string> | undefined): CustomTool;
 /**
  * Assemble the AgentOptions for the transient agent. Shared shape:
- * model + local + tools[output] + systemPrompt + apiKey.
+ * model + local + tools[output] + systemPrompt + apiKey, plus the caller's withheld builtins
+ * and memory settings when supplied (B-678).
  */
 export declare function buildTransientAgentOptions(params: {
     model: string | ModelSelection;
@@ -24,6 +25,8 @@ export declare function buildTransientAgentOptions(params: {
     systemPrompt?: string;
     apiKey?: string;
     providers?: ProviderRoutingSettings;
+    withheldBuiltinTools?: readonly BuiltinToolName[];
+    memory?: MemorySettings;
 }): AgentOptions;
 /**
  * Best-effort extraction of token usage from a run result. Local runtimes

package/dist/mcp-auth.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkZOFRNNZD_cjs = require('./chunk-ZOFRNNZD.cjs');
-var chunkQISSETTG_cjs = require('./chunk-QISSETTG.cjs');
+var chunk5645PMVU_cjs = require('./chunk-5645PMVU.cjs');
 var chunkCEGU5AVD_cjs = require('./chunk-CEGU5AVD.cjs');
 var chunkRNXXYF22_cjs = require('./chunk-RNXXYF22.cjs');
 var crypto = require('crypto');
@@ -92,7 +92,7 @@ async function getTokens(serverName) {
   }
   const filePath = storeFilePath();
   if (!fs.existsSync(filePath)) return void 0;
-  chunkQISSETTG_cjs.assertSecureModes(path.dirname(filePath), filePath);
+  chunk5645PMVU_cjs.assertSecureModes(path.dirname(filePath), filePath);
   try {
     const all = JSON.parse(fs.readFileSync(filePath, "utf8"));
     return all[serverName];

package/dist/mcp-auth.js

@@ -1,5 +1,5 @@
 import { atomicWriteJson } from './chunk-M4U24U6G.js';
-import { assertSecureModes } from './chunk-MS3TQSXU.js';
+import { assertSecureModes } from './chunk-QD6B6W6I.js';
 import { ConfigurationError } from './chunk-TNFOU6SB.js';
 import { diag } from './chunk-3OY6H3I7.js';
 import { randomBytes, createHash } from 'crypto';

package/dist/models.cjs

@@ -1,12 +1,12 @@
 'use strict';
 
 var chunk7INPXUJI_cjs = require('./chunk-7INPXUJI.cjs');
-var chunkNWWTYBD3_cjs = require('./chunk-NWWTYBD3.cjs');
+var chunk4KBI37F3_cjs = require('./chunk-4KBI37F3.cjs');
 var chunk3EE6LVWT_cjs = require('./chunk-3EE6LVWT.cjs');
-var chunkS46WJTDL_cjs = require('./chunk-S46WJTDL.cjs');
+var chunk4TEGFMSP_cjs = require('./chunk-4TEGFMSP.cjs');
 require('./chunk-NVXXWAU7.cjs');
-require('./chunk-5A4UFBHW.cjs');
-require('./chunk-QISSETTG.cjs');
+require('./chunk-A77UMVMD.cjs');
+require('./chunk-5645PMVU.cjs');
 require('./chunk-IOFMRS6T.cjs');
 var chunkEHD25JBZ_cjs = require('./chunk-EHD25JBZ.cjs');
 require('./chunk-CEGU5AVD.cjs');
@@ -85,7 +85,7 @@ function catalogTargets() {
   if (_catalogTargets !== void 0) return _catalogTargets;
   _catalogTargets = /* @__PURE__ */ new Map();
   try {
-    for (const entry of Object.values(chunkS46WJTDL_cjs.loadProviderCatalog())) {
+    for (const entry of Object.values(chunk4TEGFMSP_cjs.loadProviderCatalog())) {
       const keys = [entry.id, ...entry.aliases ?? []];
       for (const k of keys) {
         if (!_catalogTargets.has(k)) _catalogTargets.set(k, { keys });
@@ -99,7 +99,7 @@ function resolvePatchKeys(externalId) {
   const mapped = MODELS_DEV_ID_MAP[externalId] ?? externalId;
   const fromCatalog = catalogTargets().get(mapped);
   if (fromCatalog !== void 0) return fromCatalog.keys;
-  const profile = chunkS46WJTDL_cjs.getProviderProfile(mapped);
+  const profile = chunk4TEGFMSP_cjs.getProviderProfile(mapped);
   if (profile !== void 0) return [profile.name, ...profile.aliases ?? []];
   return void 0;
 }
@@ -116,9 +116,9 @@ function patchIndexFromApiJson(raw) {
       continue;
     }
     for (const [modelId, rawModel] of Object.entries(models)) {
-      const parsed = chunkS46WJTDL_cjs.catalogModelSchema.safeParse(rawModel);
+      const parsed = chunk4TEGFMSP_cjs.catalogModelSchema.safeParse(rawModel);
       if (!parsed.success) continue;
-      for (const key of keys) chunkS46WJTDL_cjs.patchModelInfo(`${key}/${modelId}`, parsed.data);
+      for (const key of keys) chunk4TEGFMSP_cjs.patchModelInfo(`${key}/${modelId}`, parsed.data);
       patched++;
     }
   }
@@ -218,7 +218,7 @@ function persistAndPatch(path, body) {
   }
 }
 async function refreshModelCatalog(opts = {}) {
-  chunkS46WJTDL_cjs.registerBuiltins();
+  chunk4TEGFMSP_cjs.registerBuiltins();
   if (fetchDisabledByEnv()) return { source: "skipped", models: 0 };
   const url = opts.url ?? process.env.THEOKIT_MODELS_URL ?? DEFAULT_URL;
   const path = cachePathFor(url);
@@ -232,12 +232,12 @@ async function refreshModelCatalog(opts = {}) {
   return persistAndPatch(path, body);
 }
 function getModelInfo(modelId) {
-  return chunkS46WJTDL_cjs.getCatalogModelInfo(modelId);
+  return chunk4TEGFMSP_cjs.getCatalogModelInfo(modelId);
 }
 
 Object.defineProperty(exports, "resolveModelCapabilities", {
   enumerable: true,
-  get: function () { return chunkNWWTYBD3_cjs.resolveModelCapabilities; }
+  get: function () { return chunk4KBI37F3_cjs.resolveModelCapabilities; }
 });
 Object.defineProperty(exports, "parseModelId", {
   enumerable: true,

package/dist/models.js

@@ -1,11 +1,11 @@
 import { Retry } from './chunk-2S4HQCDF.js';
-export { resolveModelCapabilities } from './chunk-2SFLLOMN.js';
+export { resolveModelCapabilities } from './chunk-NVQSBRG6.js';
 import { parseModelId } from './chunk-R7WIIPUR.js';
 export { parseModelId } from './chunk-R7WIIPUR.js';
-import { registerBuiltins, getCatalogModelInfo, catalogModelSchema, patchModelInfo, getProviderProfile, loadProviderCatalog } from './chunk-5HSMH2ZZ.js';
+import { registerBuiltins, getCatalogModelInfo, catalogModelSchema, patchModelInfo, getProviderProfile, loadProviderCatalog } from './chunk-CJN5CEI3.js';
 import './chunk-AGACYRJ2.js';
-import './chunk-3FSBE4PS.js';
-import './chunk-MS3TQSXU.js';
+import './chunk-3GTN4HOO.js';
+import './chunk-QD6B6W6I.js';
 import './chunk-5IUDICRK.js';
 import { boundFetch } from './chunk-Q7GYMXVC.js';
 import './chunk-TNFOU6SB.js';

package/dist/providers.cjs

@@ -1,10 +1,10 @@
 'use strict';
 
-var chunkLO6LIUZ6_cjs = require('./chunk-LO6LIUZ6.cjs');
-require('./chunk-S46WJTDL.cjs');
+var chunkR5UQL2R5_cjs = require('./chunk-R5UQL2R5.cjs');
+require('./chunk-4TEGFMSP.cjs');
 require('./chunk-NVXXWAU7.cjs');
-require('./chunk-5A4UFBHW.cjs');
-require('./chunk-QISSETTG.cjs');
+require('./chunk-A77UMVMD.cjs');
+require('./chunk-5645PMVU.cjs');
 require('./chunk-IOFMRS6T.cjs');
 require('./chunk-EHD25JBZ.cjs');
 require('./chunk-CEGU5AVD.cjs');
@@ -14,11 +14,11 @@ require('./chunk-RNXXYF22.cjs');
 
 Object.defineProperty(exports, "getProviderProfile", {
   enumerable: true,
-  get: function () { return chunkLO6LIUZ6_cjs.getProviderProfile; }
+  get: function () { return chunkR5UQL2R5_cjs.getProviderProfile; }
 });
 Object.defineProperty(exports, "listProviders", {
   enumerable: true,
-  get: function () { return chunkLO6LIUZ6_cjs.listProviders; }
+  get: function () { return chunkR5UQL2R5_cjs.listProviders; }
 });
 //# sourceMappingURL=providers.cjs.map
 //# sourceMappingURL=providers.cjs.map

package/dist/providers.js

@@ -1,8 +1,8 @@
-export { getProviderProfile, listProviders } from './chunk-NKQVLWDF.js';
-import './chunk-5HSMH2ZZ.js';
+export { getProviderProfile, listProviders } from './chunk-ULEK4OM4.js';
+import './chunk-CJN5CEI3.js';
 import './chunk-AGACYRJ2.js';
-import './chunk-3FSBE4PS.js';
-import './chunk-MS3TQSXU.js';
+import './chunk-3GTN4HOO.js';
+import './chunk-QD6B6W6I.js';
 import './chunk-5IUDICRK.js';
 import './chunk-Q7GYMXVC.js';
 import './chunk-TNFOU6SB.js';

package/dist/sandbox/bwrap.d.cts

@@ -1,9 +1,10 @@
+import type { BwrapDetection, SandboxMode } from "./types.js";
 /**
  * Codex's three canonical modes. Defined HERE because they are sandbox vocabulary, not consumer
  * configuration: `danger-full-access` means "do not wrap", and that is a decision belonging to the
  * confinement subsystem.
  */
-export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export type { SandboxMode } from "./types.js";
 /**
  * U-6 — the roots a mode may write to, answerable WITHOUT spawning anything.
  *
@@ -40,6 +41,13 @@ export interface BwrapArgvOptions {
      * sandboxed child. Omitted ⇒ inherit the parent env (backward-compatible; SDK scrub still applies).
      */
     env?: Record<string, string>;
+    /**
+     * Absolute paths the confined command must not read. Each is resolved through symlinks and masked
+     * after the writable binds: a directory becomes empty, a file reads as permission denied. A masked
+     * file still shows in the listing of its directory. Throws `TypeError` for a relative or missing
+     * path, one that contains the workspace, `/tmp` or `/`, and any list under `danger-full-access`.
+     */
+    denyReadPaths?: readonly string[];
 }
 /**
  * Pure argv builder. Returns the bwrap flags ending in `--` (caller appends `/bin/sh -c <cmd>`),
@@ -73,13 +81,7 @@ export interface BwrapProbes {
  * `try`/`catch` catches nothing; callers warn and fall back to an unconfined
  * `LocalSandbox`.
  */
-export type BwrapDetection = {
-    ok: true;
-    bin: string;
-} | {
-    ok: false;
-    reason: string;
-};
+export type { BwrapDetection } from "./types.js";
 /** Honest detection — fail-closed on every probe; NEVER throws (callers WARN + fall back). */
 export declare function detectBwrap(probes?: BwrapProbes): BwrapDetection;
 /** How many real probes ran. TEST seam — the performance gate counts this. */

package/dist/sandbox/bwrap.d.ts

@@ -1,9 +1,10 @@
+import type { BwrapDetection, SandboxMode } from "./types.js";
 /**
  * Codex's three canonical modes. Defined HERE because they are sandbox vocabulary, not consumer
  * configuration: `danger-full-access` means "do not wrap", and that is a decision belonging to the
  * confinement subsystem.
  */
-export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export type { SandboxMode } from "./types.js";
 /**
  * U-6 — the roots a mode may write to, answerable WITHOUT spawning anything.
  *
@@ -40,6 +41,13 @@ export interface BwrapArgvOptions {
      * sandboxed child. Omitted ⇒ inherit the parent env (backward-compatible; SDK scrub still applies).
      */
     env?: Record<string, string>;
+    /**
+     * Absolute paths the confined command must not read. Each is resolved through symlinks and masked
+     * after the writable binds: a directory becomes empty, a file reads as permission denied. A masked
+     * file still shows in the listing of its directory. Throws `TypeError` for a relative or missing
+     * path, one that contains the workspace, `/tmp` or `/`, and any list under `danger-full-access`.
+     */
+    denyReadPaths?: readonly string[];
 }
 /**
  * Pure argv builder. Returns the bwrap flags ending in `--` (caller appends `/bin/sh -c <cmd>`),
@@ -73,13 +81,7 @@ export interface BwrapProbes {
  * `try`/`catch` catches nothing; callers warn and fall back to an unconfined
  * `LocalSandbox`.
  */
-export type BwrapDetection = {
-    ok: true;
-    bin: string;
-} | {
-    ok: false;
-    reason: string;
-};
+export type { BwrapDetection } from "./types.js";
 /** Honest detection — fail-closed on every probe; NEVER throws (callers WARN + fall back). */
 export declare function detectBwrap(probes?: BwrapProbes): BwrapDetection;
 /** How many real probes ran. TEST seam — the performance gate counts this. */

package/dist/sandbox/deny-read.d.cts

@@ -0,0 +1,24 @@
+import type { BwrapDetection, SandboxMode } from "./types.js";
+/**
+ * The bwrap flags that make each path in `paths` unreadable inside the sandbox: `--tmpfs` for a
+ * directory, `--ro-bind /dev/null` for a file. Callers place them after the writable binds so the
+ * mask wins over a path inside the workspace or `/tmp`.
+ *
+ * Every entry is resolved through symlinks first, so reading through a link is denied too, and
+ * duplicates collapse in list order. A masked file is still listed in its directory; only reading it
+ * fails.
+ *
+ * Throws `TypeError` (never skips) for a relative or missing entry, an entry that equals or contains
+ * the working directory, `/tmp` or `/`, and any non-empty list under `danger-full-access`, where no
+ * mask can be applied.
+ */
+export declare function denyReadFlags(paths: readonly string[] | undefined, policy: {
+    mode: SandboxMode;
+    cwd: string;
+}): string[];
+/**
+ * Refuses a non-empty deny list that no confinement can honour, before a backend or a wrap exists:
+ * `danger-full-access` applies no sandbox (`TypeError`), and an undetected bubblewrap would fall back
+ * to an unconfined run, which is the leak the list exists to stop (`SandboxNotAvailableError`).
+ */
+export declare function refuseUnhonourableDenyRead(paths: readonly string[] | undefined, mode: SandboxMode, detect: () => BwrapDetection): void;

package/dist/sandbox/deny-read.d.ts

@@ -0,0 +1,24 @@
+import type { BwrapDetection, SandboxMode } from "./types.js";
+/**
+ * The bwrap flags that make each path in `paths` unreadable inside the sandbox: `--tmpfs` for a
+ * directory, `--ro-bind /dev/null` for a file. Callers place them after the writable binds so the
+ * mask wins over a path inside the workspace or `/tmp`.
+ *
+ * Every entry is resolved through symlinks first, so reading through a link is denied too, and
+ * duplicates collapse in list order. A masked file is still listed in its directory; only reading it
+ * fails.
+ *
+ * Throws `TypeError` (never skips) for a relative or missing entry, an entry that equals or contains
+ * the working directory, `/tmp` or `/`, and any non-empty list under `danger-full-access`, where no
+ * mask can be applied.
+ */
+export declare function denyReadFlags(paths: readonly string[] | undefined, policy: {
+    mode: SandboxMode;
+    cwd: string;
+}): string[];
+/**
+ * Refuses a non-empty deny list that no confinement can honour, before a backend or a wrap exists:
+ * `danger-full-access` applies no sandbox (`TypeError`), and an undetected bubblewrap would fall back
+ * to an unconfined run, which is the leak the list exists to stop (`SandboxNotAvailableError`).
+ */
+export declare function refuseUnhonourableDenyRead(paths: readonly string[] | undefined, mode: SandboxMode, detect: () => BwrapDetection): void;