@theokit/agents 9.3.0 → 9.4.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # @theokit/agents
 
+## 9.4.0
+
+### Minor Changes
+
+- 299a014: `createDelegateTool` — the agent can now ask the framework to delegate.
+
+  `@theokit/agents/tools` handed the model 23 tools and none of them delegated to a local sub-agent.
+  The capability shipped — `delegate()`, `delegateWithScoring()`, `delegateBackground()`, `Squad` —
+  but only the app could reach it. `createA2ATool` did not cover the case: its target is a remote peer,
+  inheriting none of the parent's tools, budget or authority.
+
+  The factory is deliberately thin. `delegate()` already merges the parent's tools, clamps the budget
+  and propagates authority; re-deriving any of that here would create a second owner of one rule.
+
+  It refuses at construction what would otherwise fail on the model's first call: an empty roster,
+  duplicate names (which collapse in the enum and dispatch silently to the wrong sub-agent) and a
+  missing credential. Budget and timeout failures come back as JSON the model can act on rather than
+  ending the parent's turn; an unexpected error propagates.
+
+- d6a5928: `CustomCommand.frontmatter` carries the frontmatter lines, so a product can read its own keys.
+
+  The loader knows one key (`description`). A product's commands declare more, and the sets do not
+  agree: the closest consumer reads `model`, `agent`, `subtask` and `hints`, while Claude Code's custom
+  commands declare `model` and `argument-hint`. Two vocabularies already, and neither is the
+  framework's to adopt.
+
+  Measured cost of not carrying them: that consumer wrote a 122-line loader — same directories, same
+  trust gate, same precedence — because the result gave it nowhere to read its own keys from. The lines
+  travel now, and `frontmatterValue` (already exported) reads whichever key the caller cares about.
+
+- 7825605: `loadInstructionTree` takes an `order`, so a rules folder is walked the way a rules folder means.
+
+  The predicate made a rules directory walkable and left the ordering the one an instruction TREE
+  needs — every file at a level before descending, because there the outer file states the general rule
+  and the inner one refines it. A rules FOLDER is the opposite shape: the files are peers, and the
+  contract its users depend on is that the same directory assembles the same prompt on any machine, in
+  one alphabetical pass.
+
+  Half a capability is its own kind of defect: offering the walk without the order left a caller able
+  to read a rules folder only in an order that misrepresents it.
+
+  Additive — `'outward-in'` stays the default, so no existing caller shifts.
+
+- c70eadb: `loadInstructionTree` now accepts a predicate for `fileNames`, so a rules DIRECTORY can be walked.
+
+  `fileNames.includes(entry)` matched a basename, so the walk could only collect files the caller
+  could name in advance. A rules directory is the opposite shape: the user drops arbitrarily named
+  files in and expects all of them read. That is not one product's idiosyncrasy — Claude Code reads
+  `.claude/rules/` and Cursor reads `.cursor/rules/*.mdc`, both arbitrary-name directories.
+
+  Measured consequence of the gap: the closest consumer wrote its own 112-line walk — budget, depth
+  ceiling, cycle guard and all — to ask `entry.endsWith('.md')`. The walk was ours; only the question
+  was theirs.
+
+  Additive: `fileNames` still accepts an array, with unchanged semantics.
+
+- 339852d: `loadCustomCommands` reads subdirectories, so a namespaced command is no longer invisible.
+
+  The loader stopped at `!statSync(path).isFile()`, which means a command in a subdirectory was not
+  "unsupported" — it was invisible. No warning, no error: the file sits there and the command does not
+  exist.
+
+  Namespacing is not one product's idea. Claude Code reads `.claude/commands/frontend/component.md` as
+  a namespaced command, and the closest consumer names nested files by their relative path for the same
+  reason a flat directory stops scaling past a dozen commands.
+
+  The name is now the path relative to the commands root with the extension removed
+  (`frontend/component`). How it is rendered — `frontend:component`, `frontend/component` — stays the
+  product's, because the two known products already disagree.
+
+- b30fe9f: `projectsRoot(root?)` — one owner for where every project's transcripts live.
+
+  `join(root, 'projects', …)` was written in three places: twice inside `project-index.ts`, and once in
+  the closest consumer, which restated it as `join(transcriptRoot(), 'projects')` to enumerate every
+  project for a GC sweep.
+
+  The failure mode is what makes it worth a function rather than a comment. That consumer guards its
+  enumeration with `existsSync(root) ? readdir(root) : []`, so a segment that stops matching does not
+  throw — it returns an empty list. The sweep then finds nothing, deletes nothing, and reports success.
+  A wrong path that throws is a bug report; a wrong path that returns nothing is a collector that
+  quietly stopped collecting.
+
+- e7c4d28: `InstructionBlock.scopesUnreadable` — a declared `paths:` that yields nothing is no longer
+  indistinguishable from no scope at all.
+
+  `parsePathsScope` reads lines and never fails, so a `paths:` whose value it cannot extract returned
+  `[]` — the same value as a file that declared no scope. A consumer rendering `scopes` then turned a
+  rule written for one subtree into a rule applying everywhere, and nothing said so.
+
+  Widening a scope silently is the one frontmatter failure with a consequence: the model obeys a rule
+  outside the files it was written for. The flag lets a product with a fail-closed policy drop the
+  block instead of publishing it unscoped, and `onWarn` now reports the case.
+
+### Patch Changes
+
+- 6b15741: Frontmatter is read on CRLF files instead of being reported as never closing.
+
+  `splitFrontmatter` split on `'\n'`, so on a CRLF checkout the closing line is `'---\r'`, which never
+  equalled the fence: a perfectly valid file returned "frontmatter never closes" and was skipped. On
+  Windows that is every instruction file with frontmatter, silently, with a warning blaming a missing
+  `---` that is sitting right there.
+
+  The trap ran one level deeper. `.` does not match `\r` and `$` does not match before it, so the
+  list-item pattern behind `paths:` failed on `'  - src/**\r'`. Fixing only the fence would have
+  turned "the file is skipped" into "the file is read and silently unscoped" — worse, because a rule
+  that applies everywhere looks like it works.
+
+  Line endings are now normalised at the boundary, and the closing fence is compared trimmed like the
+  opening one already was — an asymmetry that let a file open a frontmatter block it could never close.
+
+- b8f47a9: Two silent failures in the instruction-tree walk.
+
+  `paths: [unclosed` produced the scope `unclose`. The inline branch did
+  `inline.slice(1, inline.lastIndexOf(']'))`, and `lastIndexOf` returns -1 when the bracket never
+  arrives — so the slice quietly dropped the last character and handed back a scope nobody wrote.
+  Worse than an empty list, because a scope that exists suppresses `scopesUnreadable`: the block looked
+  correctly scoped, to a path matching nothing, so the rule stopped applying anywhere and said nothing.
+
+  The depth ceiling stopped in silence. The file ceiling already announced itself
+  (`instruction budget: stopped at N files`) and this one was a bare `return false` — indistinguishable
+  from a directory that had nothing left in it, which sends the reader looking for a typo in a filename
+  that is spelled correctly.
+
+- b023cef: `deleteSession` now refuses an async `removeFromRegistry` instead of reporting a delete that has not
+  happened.
+
+  The seam is synchronous by contract, and `options.removeFromRegistry?.(id) ?? false` sat at the
+  return: hand it an async remover and the field evaluated to a Promise — truthy — so `registryRemoved`
+  said the entry was gone before the removal occurred, and any rejection surfaced as an unhandled
+  rejection. That is not a corner case. `Agent.delete` returns `Promise<void>` and is the only agent
+  registry in the ecosystem, so every real caller has an async remover.
+
+  The check now runs BEFORE the transcript is unlinked, so a refused call leaves the session intact and
+  the caller can retry: await the registry removal first, then pass its outcome.
+
 ## 9.3.0
 
 ### Minor Changes

package/dist/{define-agent-3Kuf6iKM.d.ts → agent-compiler-CIPQkehU.d.ts}

@@ -1,7 +1,6 @@
-import { McpServerConfig, SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings, TrustPosture, CustomTool } from '@theokit/sdk';
-import { z } from 'zod';
+import { McpServerConfig, SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings } from '@theokit/sdk';
 import { TheokitAgentError } from '@theokit/sdk/errors';
-import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
+import { z } from 'zod';
 
 /**
  * Provider-agnostic extended-thinking knob (M1 reasoning-visibility). The common set autocompletes;
@@ -401,233 +400,4 @@ interface CompiledAgentOptions {
     skillsResolver?: SkillsSelection;
 }
 
-/**
- * M68 — the trust gate for `settingSources`.
- *
- * ## The defect this module closes
- *
- * `settingSources` enables on-disk config discovery. `'user'` reads `~/.theokit/` — the operator's
- * own machine, which no third party controls. `'project'` reads `<cwd>/.theokit/`, **including
- * `hooks.json`, which executes shell**.
- *
- * The previous API took `readonly SettingSource[]`, and its JSDoc justified the risk this way:
- * *"it is opt-in because `.theokit/` is the app's own repo (informed consent)"*. That premise holds
- * for a web app whose `cwd` is its own deploy. It does **not** hold for the class of product this
- * framework addresses — an agent whose `cwd` is a repository the user just cloned. There `.theokit/`
- * is attacker-controlled content, and enabling `'project'` is remote code execution on the first
- * `build()`.
- *
- * Documenting it did not prevent it. The measured consumer (TheoCode) did not trust the API: it
- * gated from the outside, with a `posture.allows` of its own (`chat.ts:386`, comment B-008). It
- * already **had** the right decision and could not pass it through, because the API only accepted
- * strings. The gate existed on its side and evaporated at the boundary.
- *
- * ## The evidence is the SDK's, not one invented here
- *
- * `TrustPosture` is `@theokit/sdk`'s own trust primitive, and `recordWiring`'s doc says *"a posture
- * is the only thing in this package that retains a capability"*. A bespoke type would make two trust
- * grammars coexist and drift apart (ADR 0063).
- */
-/**
- * The framework's capability vocabulary — deliberately a single name (ADR 0065).
- *
- * `allows` is all-or-nothing in the SDK: every declared `K` gets the same boolean. A finer
- * vocabulary (`hooks`, `skills`, `subagents`, `mcp`) would promise the consumer it can gate one
- * without gating the other, and the primitive does not deliver that. An API that suggests a
- * distinction the runtime does not make teaches the wrong thing, and the error only surfaces when
- * somebody depends on the distinction.
- */
-type SettingSourceCapability = 'projectSettings';
-/** Authorization to read config from the working directory. Requires the posture, never a claim. */
-interface ProjectSettingsGrant {
-    /**
-     * Typically the output of `resolveTrustPosture` — which is what gives it `source` (`'env' |
-     * 'store' | 'default'`) and therefore a refusal that says WHERE the decision came from instead of
-     * merely denying.
-     */
-    readonly trustedBy: TrustPosture<SettingSourceCapability>;
-}
-/**
- * Which on-disk config roots the agent may read.
- *
- * The asymmetry is the design: `user` is a boolean because `~/.theokit/` belongs to the operator;
- * `project` requires evidence because `<cwd>/.theokit/` may not. Omitting a root is not enabling it
- * — never "enabling without a gate". The asymmetry is inherited from the SDK itself, whose
- * `TrustPostureInput.envOverride` documents that `false` and `undefined` both mean "the operator did
- * not turn it on", not "turned it off".
- */
-interface SettingSourcesSelection {
-    /** `~/.theokit/` — the operator's machine. No gate: no third party controls it. */
-    readonly user?: boolean;
-    /** `<cwd>/.theokit/` — controlled by whoever wrote the open repository. Requires evidence. */
-    readonly project?: ProjectSettingsGrant;
-}
-/**
- * Refusal to read the working directory for lack of trust.
- *
- * Descends from `TheokitAgentError` because typed errors are an unbreakable rule here — and because
- * `isTransientError` only sees this hierarchy. A class extending plain `Error` would be invisible to
- * the predicate that separates recoverable from unrecoverable (the defect M67 fixed in five
- * classes).
- */
-declare class UntrustedSettingSourceError extends TheokitAgentError {
-    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
-    readonly trustSource: string;
-    /** The refused capability. */
-    readonly capability: SettingSourceCapability;
-    readonly name = "UntrustedSettingSourceError";
-    constructor(message: string, 
-    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
-    trustSource: string, 
-    /** The refused capability. */
-    capability: SettingSourceCapability);
-}
-/**
- * Translate the declared selection into the `SettingSource`s the SDK accepts, refusing what the
- * posture does not authorize.
- *
- * Refuses rather than ignores (ADR 0064). Ignoring would leave the product running in the belief
- * that the repository's hooks are active — a silent failure mode, on the wrong side. The SDK already
- * picked that side for the same problem: `recordWiring` throws `UngatedCapabilityError` when
- * somebody registers a capability the posture does not gate.
- *
- * @throws {UntrustedSettingSourceError} when `project` is requested and the posture does not grant it.
- */
-declare function resolveSettingSources(selection: SettingSourcesSelection | undefined): readonly SettingSource[];
-
-/**
- * M2 (theokit-ai-first) — `defineAgent`, the zero-config imperative agent surface.
- *
- * ADR-B1: `defineAgent({...})` (default-exported from a top-level `agents/<name>.ts`) is
- * the canonical zero-config surface; the `@Agent` class decorator stays the advanced/DI
- * surface. Both compile to {@link CompiledAgentOptions} and run through the same SDK
- * runtime (`createSdkAgentStream`) — one runtime, two syntaxes.
- *
- * This module is PURE metadata (sdk-runtime.md / G2): `defineAgent` describes an agent, it
- * NEVER calls an LLM. It imports only `zod` (types) + the compiler shape — no `theokit`
- * core, preserving the agents → (nothing) dependency direction (G1).
- */
-
-/**
- * Brand tag for a `defineAgent` value. `Symbol.for` (global registry, not `Symbol()`) so
- * the brand survives duplicate module instances (dual-package / bundling) — the scanner's
- * brand-check then works regardless of which copy created the definition.
- */
-declare const AGENT_BRAND: unique symbol;
-/** Config accepted by {@link defineAgent}. */
-interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
-    /** Zod schema for the request body — lifted into the typed client (M2, {@link InferAgentInput}). */
-    input?: TInput;
-    /** Model id (e.g. `claude-sonnet-4-6`). Falls back to the SDK default when omitted. */
-    model?: string;
-    /** Static system prompt. */
-    system?: string;
-    /** Extended-thinking effort. */
-    reasoningEffort?: ReasoningEffort;
-    /**
-     * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
-     * (theokit/server) and every `@theokit/sdk-tools` factory return (issue #81) — they are
-     * normalized to the internal {@link CompiledTool} shape at compile time.
-     */
-    tools?: readonly CustomTool[];
-    /**
-     * M7 — run-context: an opaque, per-agent object forwarded to every tool handler's
-     * `ctx.context` at run time (injected by the theokit adapter's tool wrapper). Set shared config
-     * (e.g. `{ projectRoot }`) ONCE at the agent level instead of baking it into each tool
-     * factory. Mirrors ai-sdk `experimental_context`, mastra `RuntimeContext`, and
-     * openai-agents-js `RunContext`. Distinct from `@Agent`'s context-window `context`.
-     */
-    context?: Record<string, unknown>;
-    /**
-     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
-     * Input guards run on the user message before the SDK runtime; a `block` fails the run fast.
-     * Built-ins live in `@theokit/agents` (`promptInjectionDetector`, `piiDetector`, `costGuard`,
-     * `unicodeNormalizer`, `outputModeration`).
-     */
-    guardrails?: readonly Guardrail[];
-    /**
-     * M14 — HITL approvals keyed by tool name. Each gated tool pauses the run and emits an
-     * `approval_required` event until approved (reuses the same `compiled.hitl` wiring the `@Agent`
-     * + `@HumanInTheLoop` path produces). A key that does not match a declared tool fails fast at
-     * compile time.
-     */
-    approvals?: Record<string, HumanInTheLoopOptions>;
-    /**
-     * M13 — skills selection: a static list (compiled straight to the SDK `skills.enabled`) OR a
-     * per-request resolver `(ctx) => string[]` (carried on `compiled.skillsResolver`, resolved by the
-     * request path against the run-context). Absent ⇒ the SDK enables every discovered skill.
-     */
-    skills?: SkillsSelection;
-    /**
-     * theokit-file-based-config — opt into `.theokit/` file-based config (skills, subagents, hooks,
-     * MCP, context, cron). The SDK discovers config from these roots under the app's `cwd`:
-     * `project` = `<cwd>/.theokit/`, `user` = `~/.theokit/`. Absent ⇒ inline (code) config only.
-     *
-     * SECURITY (M68): `project` reads `.theokit/hooks.json`, which **executes shell**, so it requires
-     * a `TrustPosture` rather than a string. This field used to take `readonly SettingSource[]`, and
-     * its own JSDoc justified the risk as *"opt-in because `.theokit/` is the app's own repo (informed
-     * consent)"*. That premise holds for a web app whose `cwd` is its own deploy; it does not hold for
-     * an agent whose `cwd` is a repository the user just cloned, where `.theokit/` is
-     * attacker-controlled content.
-     *
-     * `user` stays a plain boolean — `~/.theokit/` is the operator's own machine. Omitting a root is
-     * not enabling it. The SDK owns discovery + execution (G2 / ADR-0040); theokit resolves the
-     * selection through `resolveSettingSources` and wires the result into
-     * `Agent.create({ local.settingSources })`.
-     */
-    settingSources?: SettingSourcesSelection;
-    /**
-     * M49 — durable memory (the SDK's `.theokit/memory/` subsystem: `Remember:` capture, MEMORY.md
-     * store, auto-injected `<memory>` block, `memory_search`/`memory_get` tools). The shape is the
-     * SDK's own `MemorySettings` — the canonical runtime contract. Projected into
-     * `Agent.create({ memory })` by `assembleM8CreateOptions`.
-     */
-    memory?: MemorySettings;
-    /**
-     * Code `Plugin` objects forwarded to `Agent.create({ plugins })` — EXTENSION units (tools,
-     * commands, model providers, memory adapters). For lifecycle interception use {@link hooks}.
-     */
-    plugins?: readonly unknown[];
-    /**
-     * Lifecycle hooks keyed by `HookName` (`pre_tool_call` may veto via `{ block, message }`). Set by
-     * the builder's `hooks()`; converted into a code plugin at `build()` and never reaching the SDK
-     * under this name — the plugin is the TRANSPORT, this is the contract callers write against.
-     */
-    hooks?: HookHandlers | Readonly<Record<string, unknown>>;
-    /**
-     * MCP servers available to the agent — the builder-chain equivalent of the `@MCP` class
-     * decorator. Each key is a server name; the value is the server configuration. Forwarded
-     * unchanged to `Agent.create({ mcpServers })` (the SDK owns MCP execution). Absent ⇒ no MCP.
-     */
-    mcpServers?: McpServersMap;
-}
-/**
- * A branded agent definition — the value {@link defineAgent} returns.
- *
- * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `AgentBuilder.create()` builder
- * threads its accumulated literal tool names here (`.build()` returns `AgentDefinition<TInput,
- * 'a' | 'b'>`), so the generated client (`.theokit/agents.d.ts`) can expose them via
- * {@link InferAgentToolNames}. `defineAgent` leaves it `string` (its tools array carries no literal
- * names). Never present at runtime.
- */
-type AgentDefinition<TInput extends z.ZodType = z.ZodType, TTools extends string = string> = DefineAgentConfig<TInput> & {
-    readonly [AGENT_BRAND]: true;
-    readonly __toolNames?: TTools;
-};
-/** Infer the request type of an agent definition from its `input` Zod schema. */
-type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
-/**
- * Infer the tool-name union of an agent definition (M8). Yields the literal union for agents built
- * with the `AgentBuilder.create()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
- * whose tools array carries no literal names.
- */
-type InferAgentToolNames<T> = T extends AgentDefinition<z.ZodType, infer N> ? N : never;
-/** Brand-check: is `value` a {@link defineAgent} result? */
-declare function isAgentDefinition(value: unknown): value is AgentDefinition;
-/**
- * Lower a definition to the SDK-ready {@link CompiledAgentOptions} — the same shape
- * `compileAgent` (decorator path) produces, so both surfaces converge on one runtime.
- */
-declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOptions;
-
-export { type AgentDefinition as A, type BudgetOptions as B, type CompiledAgentOptions as C, type DefineAgentConfig as D, type Guardrail as G, type HumanInTheLoopOptions as H, type InferAgentInput as I, type MainLoopMeta as M, type PolicyHandler as P, type ReasoningEffort as R, type SettingSourcesSelection as S, type ToolOptions as T, UntrustedSettingSourceError as U, type CompiledTool as a, type ApprovalOptions as b, AGENT_BRAND as c, type AgentOptions as d, CostBudgetExceededError as e, type GuardrailAction as f, type GuardrailPhase as g, type GuardrailResult as h, GuardrailViolationError as i, type InferAgentToolNames as j, type MainLoopOptions as k, type McpServersMap as l, type ProjectSettingsGrant as m, type SettingSourceCapability as n, type SkillsRequestContext as o, type SkillsSelection as p, type TimeoutAction as q, type ToolWalkResult as r, type ToolboxOptions as s, type ToolboxWalkResult as t, compileAgentDefinition as u, compileTools as v, isAgentDefinition as w, resolveEnabledSkills as x, resolveSettingSources as y, type ProjectContextOptions as z };
+export { type ApprovalOptions as A, type BudgetOptions as B, type CompiledAgentOptions as C, type Guardrail as G, type HumanInTheLoopOptions as H, type McpServersMap as M, type PolicyHandler as P, type ReasoningEffort as R, type SkillsSelection as S, type ToolOptions as T, type MainLoopMeta as a, type CompiledTool as b, type AgentOptions as c, CostBudgetExceededError as d, type GuardrailAction as e, type GuardrailPhase as f, type GuardrailResult as g, GuardrailViolationError as h, type MainLoopOptions as i, type SkillsRequestContext as j, type TimeoutAction as k, type ToolWalkResult as l, type ToolboxOptions as m, type ToolboxWalkResult as n, compileTools as o, type ProjectContextOptions as p, resolveEnabledSkills as r };