@theokit/sdk 4.63.4-next.0 → 4.63.5

package/dist/index.d.ts

@@ -858,11 +858,29 @@ declare class Agent {
      */
     static describe(agentId: string): Promise<AgentDescription>;
     /**
-     * Permanently delete a cloud agent.
+     * Permanently delete a registered agent — local or cloud.
+     *
+     * Backport of #612 (fixed on the 5.x line in `5.3.1`). This HYDRATES before removing, and until it
+     * did the method was a no-op against the persisted registry whenever the agent was not already in
+     * this process's memory. Which is every agent in a freshly started process: `removeRegisteredAgent`
+     * only schedules a save when the entry was in the Map, so `agents.delete()` returned `false`,
+     * nothing was scheduled, and `flushRegistrySaves()` flushed an empty queue. The entry survived and
+     * this returned normally, so a caller had no way to notice.
+     *
+     * Every neighbouring mutator already did this — `rename` and `archive` reach
+     * `getRegisteredAgentOrThrow`, which hydrates on a miss. `delete` was the only one that did not.
+     *
+     * `options.cwd` is read rather than defaulted away: it is declared on `AgentOperationOptions`, and
+     * hydrating `process.cwd()` unconditionally is an option that compiles and does nothing, on the one
+     * path that is supposed to remove data.
+     *
+     * Deleting an unknown id still resolves rather than throwing, deliberately — matching 5.x. It is a
+     * breaking change for callers that delete idempotently, and an entry and its transcript can
+     * legitimately outlive one another in both directions.
      *
      * @public
      */
-    static delete(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+    static delete(agentId: string, options?: AgentOperationOptions): Promise<void>;
 }
 
 /**

package/dist/index.js

@@ -8,15 +8,15 @@ import { Workflow, agentStep } from './chunk-OSEG74VJ.js';
 export { Workflow, agentStep, fn } from './chunk-OSEG74VJ.js';
 import './chunk-BZRFXJHA.js';
 import './chunk-HY66GLM6.js';
-export { Cron } from './chunk-GPKAF7SG.js';
-import { MEMORY_EMBEDDING_ADAPTERS, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-25BD2R5G.js';
-export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-25BD2R5G.js';
+export { Cron } from './chunk-2OQHBPPV.js';
+import { MEMORY_EMBEDDING_ADAPTERS, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-GP7NHU3R.js';
+export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-GP7NHU3R.js';
 import { configure, submit, list, get, cancel, subscribe } from './chunk-A46SWMIF.js';
 export { emitRunEvent } from './chunk-A46SWMIF.js';
 import './chunk-4FFBAUFS.js';
 import './chunk-K2BQQ445.js';
 import './chunk-L3MTL4NA.js';
-import './chunk-K5OJUYSZ.js';
+import './chunk-NDGGJQTZ.js';
 import './chunk-2SFBB54R.js';
 import './chunk-UBDMVMBZ.js';
 import './chunk-H73MEMQB.js';
@@ -54,8 +54,8 @@ import { withCwdMutex } from './chunk-Q5EWJPRY.js';
 export { withCwdMutex } from './chunk-Q5EWJPRY.js';
 export { TASK_RESERVED_PREFIXES, isValidTaskId } from './chunk-KQRW2GPZ.js';
 import { replaceFileAtomic } from './chunk-2GUYQR5P.js';
-import './chunk-LXI4XZEC.js';
-import './chunk-UFLD2HEV.js';
+import './chunk-LKBEROHN.js';
+import './chunk-247ZTLNU.js';
 import './chunk-LXQ6HKPS.js';
 import './chunk-A4JVILQU.js';
 import { parseModelId } from './chunk-R7WIIPUR.js';
@@ -1705,7 +1705,7 @@ function isBuiltAgent(m) {
   return typeof m.send === "function";
 }
 async function materialize(def, index) {
-  const { Agent: Agent2 } = await import('./agent-3JK7VXNN.js');
+  const { Agent: Agent2 } = await import('./agent-Y25FRHPL.js');
   return Agent2.create({
     // `AgentDefinition.model` admits the sentinel `'inherit'`, which is not a model id. Inheriting
     // here means "declare nothing and let the default apply" — forwarding the literal would create

package/dist/internal/agent-loop/replay-messages.d.ts

@@ -0,0 +1,41 @@
+import type { SessionMessage } from "../../types/session-message.js";
+import type { LlmMessage } from "../llm/types.js";
+/**
+ * Rebuild the model's history from a session's stored turns.
+ *
+ * ## Why this exists
+ *
+ * The replay used to be one line — `content: [{ type: "text", text: msg.text }]` — and `text` is the
+ * FLAT projection, in which a tool call folds to `[tool call] NAME` and a result to
+ * `[tool result] <body>`. So a resumed session showed the model its own prior turn as prose
+ * containing a marker, and the model did the reasonable thing with a pattern it is shown: it wrote
+ * the marker instead of calling the tool (usetheokit/theokit#631). A consumer saw
+ * `"…report its output.[tool call] run_shell"` in the assistant's reply, with no tool call behind it.
+ *
+ * The structured projection was already there. `narrowToSessionMessage` returns BOTH `text` and
+ * `parts`, and `parts` carries the call id, the tool name and the arguments — everything the flat
+ * form destroys. Nothing read it: `msg.parts` appeared nowhere in the shipped bundle.
+ *
+ * ## The shape it produces
+ *
+ * `SessionMessagePart` and `LlmContentPart` agree field for field on all three cases, which is what
+ * makes this a mapping rather than a translation. What does NOT carry over is the grouping: a
+ * `tool_result` may not travel in an assistant message. The live loop already settles that —
+ * `loop.ts` pushes results as `{ role: "user", content: toolResults }` — so a replayed turn is split
+ * the same way rather than inventing a second convention for the same provider wire.
+ *
+ * ## When it falls back
+ *
+ * `parts` is optional and its absence means "this projection carries no structure", never "this turn
+ * had none" — a `SessionMessage` built in memory during a live turn has only `text`. So a message
+ * without parts replays exactly as before. That is also what keeps this safe for a session stored by
+ * an older SDK: those rows have no `parts`, and they keep the behaviour they were written under.
+ *
+ * ## An empty text part is dropped
+ *
+ * A `{ type: "text", text: "" }` survives the projection — a turn that was only a tool call has one,
+ * because `partToText` folds the call and leaves the text empty. Several provider wires reject an
+ * empty text block outright, and none of them need it, so it does not travel. Dropping it is also
+ * what makes the `own.length > 0` guard below meaningful rather than incidental.
+ */
+export declare function replayMessages(prior: readonly SessionMessage[]): LlmMessage[];

package/dist/internal/local-agent/local-option-keys.d.ts

@@ -0,0 +1,2 @@
+/** The declared surface, for the lint that keeps it in step with the interface. */
+export declare function knownLocalOptionKeys(): ReadonlySet<string>;

package/dist/internal/persistence/index.cjs

@@ -7,7 +7,7 @@ var chunk5VB22SYX_cjs = require('../../chunk-5VB22SYX.cjs');
 var chunkUU36SHFY_cjs = require('../../chunk-UU36SHFY.cjs');
 var chunkZF2LDKQQ_cjs = require('../../chunk-ZF2LDKQQ.cjs');
 var chunkUALX2J2Q_cjs = require('../../chunk-UALX2J2Q.cjs');
-var chunkAQO3NSRG_cjs = require('../../chunk-AQO3NSRG.cjs');
+var chunkAKJP2STZ_cjs = require('../../chunk-AKJP2STZ.cjs');
 require('../../chunk-4ZHTIJNE.cjs');
 require('../../chunk-XL7Q7HB2.cjs');
 require('../../chunk-EG4QM7ZJ.cjs');
@@ -112,15 +112,15 @@ Object.defineProperty(exports, "replaceFileAtomic", {
 });
 Object.defineProperty(exports, "displayTheokitHome", {
   enumerable: true,
-  get: function () { return chunkAQO3NSRG_cjs.displayTheokitHome; }
+  get: function () { return chunkAKJP2STZ_cjs.displayTheokitHome; }
 });
 Object.defineProperty(exports, "getProfilesRoot", {
   enumerable: true,
-  get: function () { return chunkAQO3NSRG_cjs.getProfilesRoot; }
+  get: function () { return chunkAKJP2STZ_cjs.getProfilesRoot; }
 });
 Object.defineProperty(exports, "getTheokitHome", {
   enumerable: true,
-  get: function () { return chunkAQO3NSRG_cjs.getTheokitHome; }
+  get: function () { return chunkAKJP2STZ_cjs.getTheokitHome; }
 });
 exports.casUpdate = casUpdate;
 exports.createExclusive = createExclusive;

package/dist/internal/persistence/index.js

@@ -5,7 +5,7 @@ export { applyWalWithFallback, isCorruptionError, openSqliteResilient } from '..
 export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-3O42QOMJ.js';
 export { withCwdMutex } from '../../chunk-Q5EWJPRY.js';
 export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-2GUYQR5P.js';
-export { displayTheokitHome, getProfilesRoot, getTheokitHome } from '../../chunk-UFLD2HEV.js';
+export { displayTheokitHome, getProfilesRoot, getTheokitHome } from '../../chunk-247ZTLNU.js';
 import '../../chunk-ZZMZWBR6.js';
 import '../../chunk-D4CUGAKZ.js';
 import '../../chunk-XEQ3TM66.js';

package/dist/internal/runtime/compat/foreign-config-sources.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The foreign configuration dialects this SDK can read, and what each one PRESUMES.
+ *
+ * ## Why a registry and not a list of directory names
+ *
+ * `projectConfigRoots` returned `[".theokit", ".claude"]` — two paths — and that shape is what
+ * usetheokit/theokit-sdk#522 fell through. A path says WHERE a file lives. It does not say how the
+ * file is parsed, and it does not say what runtime the commands inside it were written against.
+ *
+ * Claude Code defines `$CLAUDE_PROJECT_DIR` for the hook commands in its `settings.json`, and its
+ * documentation tells authors to reach project files through it — an absolute path would break for
+ * every other person on the team, so the shape that failed here is the shape upstream recommends.
+ * This SDK read the file and ran the command without the variable. `sh` expands an unset variable to
+ * the empty string, so
+ *
+ *     bash "$CLAUDE_PROJECT_DIR/.claude/hooks/guard.sh"   became   bash "/.claude/hooks/guard.sh"
+ *
+ * which does not exist, which a hook runner correctly reads as a refusal. Every turn denied, in any
+ * repository that also had Claude Code set up, with a message naming a file that was present and
+ * executable all along.
+ *
+ * Importing a format means accepting the contract that format presumes. An adapter is where that
+ * contract is written down, so the next dialect (`.codex/` is the obvious one) declares its own
+ * instead of inheriting a hole.
+ *
+ * ## What an adapter deliberately does NOT do
+ *
+ * It does not make the foreign source trusted, and it does not make its hooks permissive: a script
+ * that exits non-zero is still a refusal. It supplies the variables the format's authors were
+ * entitled to assume, and nothing else — `env` here is merged over the scrubbed inherit policy by
+ * `spawnAndCollect`, so it adds names rather than widening what a child can see.
+ *
+ * @internal
+ */
+/** The Claude Code CLI's project configuration directory. */
+export declare const CLAUDE_DIR_NAME = ".claude";
+/** A configuration dialect this SDK understands. `theokit` is native; the rest are foreign. */
+export interface ConfigSourceAdapter {
+    /** Stable identifier, and what a consumer names to opt in. */
+    readonly kind: string;
+    /** The project-relative directory the dialect keeps its configuration in. */
+    readonly dirName: string;
+    /**
+     * Variables the dialect's own runtime defines for commands it executes.
+     *
+     * Empty for the native source: a `.theokit/` hook is written against THIS runtime and inherits it
+     * already. Non-empty is what makes a foreign command runnable rather than silently broken.
+     */
+    runtimeEnv(cwd: string): Record<string, string>;
+}
+/** The native source. Always read, never opted into, always first for precedence. */
+export declare const NATIVE_SOURCE: ConfigSourceAdapter;
+/**
+ * Claude Code.
+ *
+ * `CLAUDE_PROJECT_DIR` is the documented way for a hook command in `settings.json` to reach a file
+ * in the project. Only that one variable is supplied: `$CLAUDE_PLUGIN_ROOT` and the rest of that
+ * runtime's surface are NOT defined here, because supplying a name whose value this SDK would have
+ * to invent is worse than leaving it unset — an invented root sends a script somewhere real and
+ * wrong, where an unset one fails loudly.
+ */
+export declare const CLAUDE_CODE_SOURCE: ConfigSourceAdapter;
+/**
+ * The adapter whose directory an absolute config path sits under, or `undefined` for a path that
+ * belongs to no registered dialect.
+ *
+ * Matched on the path SEGMENT rather than with `includes`, so a workspace that happens to live under
+ * `/home/me/.claude-backups/repo` does not read as a Claude Code source.
+ */
+export declare function adapterForConfigPath(path: string): ConfigSourceAdapter | undefined;
+/**
+ * Variable references in a shell command that nothing will define.
+ *
+ * The second half of #522, and the half that cost the debugging session. `sh` expands an unset
+ * variable to the empty string and says nothing, so the failure surfaces ten characters later as a
+ * path: `bash: /.claude/hooks/guard.sh: No such file or directory` — which reads as "your script is
+ * missing" while the script is present and executable. Nothing in that message contains the name of
+ * the variable that was actually missing, so the reader looks in the wrong place.
+ *
+ * Checked against BOTH the process environment and the variables the dialect supplies, because
+ * either is a legitimate source: a hook may reasonably use `$HOME`.
+ *
+ * ## What it deliberately does not try to be
+ *
+ * This is not a shell parser. It finds `$NAME` and `${NAME}` outside single quotes, which is the
+ * shape a config file's hook commands take. It does NOT understand `${NAME:-default}` (a default
+ * makes the variable optional, so it is not reported), assignments earlier in the same command, or
+ * variables a sourced script exports. A false NEGATIVE there costs the old behaviour — the confusing
+ * path error — and a false positive would deny a hook that would have worked, so the parse errs
+ * toward silence and the check only ever ADDS a name to a failure that already happened.
+ */
+export declare function undefinedVariablesIn(command: string, supplied: Readonly<Record<string, string>>, env?: Readonly<Record<string, string | undefined>>): string[];

package/dist/internal/runtime/hooks/hooks-executor.d.ts

@@ -4,6 +4,15 @@ export interface HookCommand {
     matcher?: string;
     /** Optional timeout in ms; defaults to 30s. */
     timeoutMs?: number;
+    /**
+     * The config file this command was declared in.
+     *
+     * Carried so the executor can supply the runtime contract the declaring DIALECT presumes — a
+     * command from `.claude/settings.json` is written against Claude Code's runtime and expects
+     * `$CLAUDE_PROJECT_DIR` to exist (#522). Absent for a command built in memory, which is native by
+     * construction.
+     */
+    sourcePath?: string;
 }
 export interface HookDecision {
     decision: "allow" | "deny" | "feedback";

package/dist/internal/runtime/hooks/hooks-source.d.ts

@@ -20,6 +20,15 @@ export interface HookCommand {
     command: string;
     matcher?: string;
     timeoutMs?: number;
+    /**
+     * The config file this command was declared in.
+     *
+     * Carried so the executor can supply the runtime contract the declaring DIALECT presumes — a
+     * command from `.claude/settings.json` is written against Claude Code's runtime and expects
+     * `$CLAUDE_PROJECT_DIR` to exist (#522). Absent for a command built in memory, which is native by
+     * construction.
+     */
+    sourcePath?: string;
 }
 export interface HookConfig {
     hooks?: Partial<Record<HookEvent, HookCommand[]>>;

package/dist/subagents-loader-UCNO7FUH.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+var chunk43ZQRWAP_cjs = require('./chunk-43ZQRWAP.cjs');
+require('./chunk-AKJP2STZ.cjs');
+require('./chunk-4CLOXP6H.cjs');
+require('./chunk-4ZHTIJNE.cjs');
+require('./chunk-XL7Q7HB2.cjs');
+require('./chunk-EG4QM7ZJ.cjs');
+
+
+
+Object.defineProperty(exports, "loadSubagents", {
+  enumerable: true,
+  get: function () { return chunk43ZQRWAP_cjs.loadSubagents; }
+});
+//# sourceMappingURL=subagents-loader-UCNO7FUH.cjs.map
+//# sourceMappingURL=subagents-loader-UCNO7FUH.cjs.map

package/dist/{subagents-loader-YEUFFPAL.cjs.map → subagents-loader-UCNO7FUH.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-YEUFFPAL.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-UCNO7FUH.cjs"}

package/dist/subagents-loader-XP5ERVDZ.js

@@ -0,0 +1,8 @@
+export { loadSubagents } from './chunk-LKBEROHN.js';
+import './chunk-247ZTLNU.js';
+import './chunk-LXQ6HKPS.js';
+import './chunk-ZZMZWBR6.js';
+import './chunk-D4CUGAKZ.js';
+import './chunk-XEQ3TM66.js';
+//# sourceMappingURL=subagents-loader-XP5ERVDZ.js.map
+//# sourceMappingURL=subagents-loader-XP5ERVDZ.js.map

package/dist/{subagents-loader-CRT5LLL3.js.map → subagents-loader-XP5ERVDZ.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-CRT5LLL3.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-XP5ERVDZ.js"}

package/dist/subagents-loader.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkCQBXOJ6U_cjs = require('./chunk-CQBXOJ6U.cjs');
-require('./chunk-AQO3NSRG.cjs');
+var chunk43ZQRWAP_cjs = require('./chunk-43ZQRWAP.cjs');
+require('./chunk-AKJP2STZ.cjs');
 require('./chunk-4CLOXP6H.cjs');
 var chunk4ZHTIJNE_cjs = require('./chunk-4ZHTIJNE.cjs');
 require('./chunk-XL7Q7HB2.cjs');
@@ -24,7 +24,7 @@ function resolveSources(options) {
 }
 async function discoverSubagents(cwd, options) {
   const sources = resolveSources(options);
-  return chunkCQBXOJ6U_cjs.loadSubagents(cwd, sources.includes("project"), void 0);
+  return chunk43ZQRWAP_cjs.loadSubagents(cwd, sources.includes("project"), void 0);
 }
 async function loadSubagentDefinition(name, cwd, options) {
   return (await discoverSubagents(cwd, options))[name];

package/dist/subagents-loader.js

@@ -1,5 +1,5 @@
-import { loadSubagents } from './chunk-LXI4XZEC.js';
-import './chunk-UFLD2HEV.js';
+import { loadSubagents } from './chunk-LKBEROHN.js';
+import './chunk-247ZTLNU.js';
 import './chunk-LXQ6HKPS.js';
 import { ConfigurationError } from './chunk-ZZMZWBR6.js';
 import './chunk-D4CUGAKZ.js';

package/docs/error-codes.md

@@ -68,11 +68,11 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `handoff_target_invalid` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:116` |
 | `handoff_target_required` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:111` |
 | `hitl_timeout` | domain | HitlTimeoutError | `packages/sdk/src/internal/runtime/tools/hitl-middleware.ts:39` |
-| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:429` |
-| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:234` |
-| `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:152` +2 |
-| `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:143` |
-| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:228` |
+| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:433` |
+| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:265` |
+| `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:183` +2 |
+| `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:174` |
+| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:259` |
 | `interactive_unavailable` | domain | InteractiveUnavailableError | `packages/sdk/src/interactive/types.ts:20` |
 | `INTERNAL_SERVER_ERROR` | domain | — | `packages/sdk/src/server/errors-envelope.ts:100` |
 | `invalid_argument` | domain | TheokitAgentError | `packages/sdk/src/compaction.ts:79` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.63.4-next.0",
+  "version": "4.63.5",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",