@theokit/sdk 1.5.0

package/dist/internal/personality/switch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * performPersonalitySwitch — orchestrates the full lifecycle of a
+ * personality activation: store mutation, optional history reset,
+ * transcript marker injection, and cache invalidation (T5.1, ADR D164).
+ *
+ * The marker is emitted as a **user role** message because (a) the
+ * switch is a directive from the operator (not a model utterance), and
+ * (b) LLMs treat user-role lines as instructions that survive history
+ * compaction (EC-D from arXiv:2412.00804).
+ *
+ * Same-slug switches are no-ops: no marker, no cache invalidation, no
+ * store write (EC-18).
+ *
+ * @internal
+ */
+import { PersonalityRegistry } from "./registry.js";
+import type { PersonalityStore } from "./store.js";
+export interface PerformPersonalitySwitchArgs {
+    agentId: string;
+    /** Previous active slug (undefined = no active preset). */
+    prevSlug: string | undefined;
+    /** Next active slug or reserved clear alias (none / default / neutral). */
+    requestedName: string;
+    registry: PersonalityRegistry;
+    store: PersonalityStore;
+    invalidateCache: (reason: string) => Promise<void>;
+    appendSessionMessage: (msg: {
+        role: "user" | "assistant";
+        text: string;
+    }) => void;
+    clearSession?: () => void;
+    opts: {
+        save?: boolean;
+        reset?: boolean;
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Personality preset types + Zod frontmatter schema (T1.1, ADR D161).
+ *
+ * **EC-C:** name regex is **lowercase-only** (NO `/i` flag) to prevent
+ * `Coder` vs `coder` becoming distinct registry keys (Map verbatim).
+ * Forcing lowercase eliminates the ambiguity at validation time.
+ *
+ * @internal
+ */
+export type PersonalityFrontmatter = z.infer<typeof PersonalityFrontmatterSchema>;
+/**
+ * Resolved personality preset — frontmatter + body + source provenance.
+ * Defined publicly in `types/agent.ts` so the DTS bundle never crosses
+ * `internal/`. Re-exported here for ergonomic internal callers.
+ *
+ * @public
+ */
+export type { PersonalityPreset } from "../../types/agent.js";

package/dist/internal/plugins/context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PluginContext implementation + dev-mode seal (T1.2, ADR D99).
+ *
+ * `createPluginContext()` returns a fresh `{ ctx, registrations }` pair
+ * for each plugin. In dev mode (`NODE_ENV !== "production"`) the context
+ * is wrapped in a Proxy that throws on `set`/`delete` to catch plugin
+ * abuse early. In production the raw impl is returned (zero overhead).
+ *
+ * @internal
+ */
+import type { CommandHandler, HookHandler, HookName, PluginContext } from "./types.js";
+interface CommandEntry {
+    name: string;
+    handler: CommandHandler;
+    description?: string;
+}
+interface InjectedMessage {
+    content: string;
+    role: "user" | "system";
+}
+export interface PluginRegistrations {
+    tools: CustomTool[];
+    commands: CommandEntry[];
+    hooks: Map<HookName, HookHandler[]>;
+    injected: InjectedMessage[];
+}
+export declare function createPluginContext(): {
+    ctx: PluginContext;
+    registrations: PluginRegistrations;
+};
+export {};

package/dist/internal/plugins/manager.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PluginManager — constructs PluginContext per plugin, invokes register()
+ * once, aggregates registrations + provider profiles + memory factories
+ * (T1.3, ADRs D97-D101).
+ *
+ * @internal
+ */
+import { type PluginRegistrations } from "./context.js";
+import type { MemoryProviderFactory, Plugin, PreToolCallContext, PreToolCallDecision } from "./types.js";
+export interface ProviderEntry {
+    pluginName: string;
+    profile: ProviderProfile;
+}
+export interface MemoryEntry {
+    pluginName: string;
+    createProvider: MemoryProviderFactory;
+}
+export interface AggregatedPlugins {
+    tools: PluginRegistrations["tools"];
+    commands: PluginRegistrations["commands"];
+    hooks: PluginRegistrations["hooks"];
+    injected: PluginRegistrations["injected"];
+    providerProfiles: ProviderEntry[];
+    memoryProviders: MemoryEntry[];
+}
+export declare class PluginManager {
+    #private;
+    initialize(plugins: ReadonlyArray<Plugin>): Promise<void>;
+    get aggregated(): Readonly<AggregatedPlugins>;
+    /**
+     * Run all `pre_tool_call` hooks; first decision with `block: true` wins.
+     * D101: veto pattern — return `{ block: true, message }` makes the loop
+     * surface a tool_result with `isError: false, content: message` so the
+     * LLM can self-correct.
+     */
+    runPreToolCallHooks(ctx: PreToolCallContext): Promise<PreToolCallDecision | undefined>;
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Plugin contract types (T1.1, ADRs D97-D101).
+ *
+ * Discriminated union by `kind`:
+ *   - `"general"` — registers tools/hooks/commands via `register(ctx)`.
+ *   - `"model-provider"` — declares a `ProviderProfile` consumed by router.
+ *   - `"memory"` — supplies a memory provider factory.
+ *
+ * Hooks are a fixed enum (D100) to prevent sprawl; `pre_tool_call` supports
+ * veto via `{ block: true, message }` (D101) so plugins can implement safety
+ * guards without crashing the agent loop.
+ *
+ * @public
+ */
+import type { CustomTool } from "../../types/agent.js";
+import type { ProviderProfile } from "../providers/types.js";
+export type HookName = "pre_tool_call" | "post_tool_call" | "pre_llm_call" | "post_llm_call" | "on_session_start" | "on_session_end" | "transform_tool_result" | "transform_llm_output" | "pre_user_send" | "post_assistant_reply";
+export interface PreToolCallContext {
+    name: string;
+    args: Record<string, unknown>;
+    agentId: string;
+    runId: string;
+}
+export interface PreToolCallDecision {
+    block: true;
+    message: string;
+}
+/**
+ * Context passed to `pre_user_send` hook handlers (ADR D145).
+ *
+ * @public
+ */
+export interface PreUserSendContext {
+    prompt: string;
+    agentId: string;
+    runId: string;
+    /** Caller-supplied memory context, flowing through from `AgentOptions.memoryContext`. */
+    memoryContext?: import("../../types/memory-adapter.js").MemoryContext;
+    /** Forwarded `AbortSignal` so adapter recall HTTP can be cancelled mid-flight (EC-H). */
+    signal?: AbortSignal;
+}
+/**
+ * Optional result returned by `pre_user_send` handlers. The agent loop
+ * concatenates `recalledContext` from all handlers and injects it as a
+ * `<memory-context>...</memory-context>` block before the user prompt.
+ *
+ * @public
+ */
+export interface PreUserSendResult {
+    recalledContext?: string;
+}
+/**
+ * Context passed to `post_assistant_reply` hook handlers (ADR D145).
+ * Fire-and-forget — exceptions are caught and surfaced to stderr; the
+ * caller's `wait()` never blocks on this dispatch.
+ *
+ * @public
+ */
+export interface PostAssistantReplyContext {
+    prompt: string;
+    reply: string;
+    agentId: string;
+    runId: string;
+    memoryContext?: import("../../types/memory-adapter.js").MemoryContext;
+}
+export type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;
+export type CommandHandler = (args: Record<string, unknown>) => Promise<string> | string;
+export interface CommandOptions {
+    description?: string;
+}
+export interface PluginContext {
+    /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */
+    registerTool(tool: CustomTool): void;
+    /** Register a slash-command-style handler. Consumed by CLI/bot wrappers; NOT used by the agent loop. */
+    registerCommand(name: string, handler: CommandHandler, opts?: CommandOptions): void;
+    /** Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`. */
+    on(hook: HookName, handler: HookHandler): void;
+    /** Inject a user/system message into the next agent turn. v1 supports only `on_session_start` context. */
+    injectMessage(content: string, role?: "user" | "system"): void;
+}
+interface BasePlugin {
+    name: string;
+    version: string;
+}
+export type Plugin = (BasePlugin & {
+    kind: "general";
+    register: (ctx: PluginContext) => void | Promise<void>;
+}) | (BasePlugin & {
+    kind: "model-provider";
+    profile: ProviderProfile;
+}) | (BasePlugin & {
+    kind: "memory";
+    createProvider: MemoryProviderFactory;
+});
+/**
+ * Identity helper for plugin authors. TS-only convenience — preserves
+ * inferred type without forcing manual `Plugin` annotation.
+ *
+ * @public
+ */
+export declare function definePlugin<P extends Plugin>(p: P): P;
+export {};

package/dist/internal/providers/builtin/anthropic.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderProfile } from "../types.js";
+export declare const ANTHROPIC: ProviderProfile;

package/dist/internal/providers/builtin/bedrock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * AWS Bedrock profile (Adoption Roadmap #8; ADRs D286-D302).
+ *
+ * Bearer-only auth via `AWS_BEARER_TOKEN_BEDROCK` env (GA Sep 2025).
+ * Optional `@aws/bedrock-token-generator` peer dep auto-refreshes short-term
+ * tokens (D287). Transport via native `fetch`; no `@aws-sdk/*` dependency.
+ *
+ * Model IDs follow the `bedrock/{aws-id}` convention so the router can
+ * infer the provider via prefix routing (D186). The client strips the
+ * `bedrock/` prefix before building the URL.
+ *
+ * @internal
+ */
+export declare const BEDROCK: ProviderProfile;
+/** Strip `"bedrock/"` prefix so the raw AWS model id is used in the URL. */
+export declare function stripBedrockPrefix(modelId: string): string;
+/**
+ * Infer AWS region from a Bedrock model id prefix (D290).
+ *
+ * `global.*` routes via `us-east-1` (AWS default entrypoint for global
+ * inference profiles).
+ */
+export declare function inferRegionFromModelId(modelId: string): string | undefined;
+/** Resolve baseUrl from model id; falls back to `AWS_REGION` env or `us-east-1`. */
+export declare function resolveBedrockBaseUrl(modelId: string): string;

package/dist/internal/providers/builtin/gemini.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderProfile } from "../types.js";
+/**
+ * Gemini via OpenRouter passthrough. Direct Gemini API uses a different
+ * dialect (`generateContent`); SDK currently routes through OpenRouter's
+ * OpenAI-compatible endpoint so the chat_completions transport works.
+ *
+ * A future plugin `@theokit-provider-gemini-direct` can override this with
+ * `apiMode: "gemini_generate_content"` once that transport ships.
+ */
+export declare const GEMINI: ProviderProfile;

package/dist/internal/providers/builtin/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Eager registration of builtin providers (T3.3). Side-effect import:
+ * importing this module registers the 4 builtins with the registry.
+ *
+ * Lazy user-plugin discovery is handled by `discovery.ts` (T3.4).
+ *
+ * @internal
+ */
+import { ANTHROPIC } from "./anthropic.js";
+import { BEDROCK } from "./bedrock.js";
+import { GEMINI } from "./gemini.js";
+import { LLAMACPP } from "./llamacpp.js";
+import { LMSTUDIO } from "./lmstudio.js";
+import { OLLAMA } from "./ollama.js";
+import { OPENAI } from "./openai.js";
+import { OPENROUTER } from "./openrouter.js";
+import { VERTEX } from "./vertex.js";
+export declare function registerBuiltins(): void;
+export { ANTHROPIC, BEDROCK, GEMINI, LLAMACPP, LMSTUDIO, OLLAMA, OPENAI, OPENROUTER, VERTEX };

package/dist/internal/providers/builtin/llamacpp.d.ts

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

package/dist/internal/providers/builtin/lmstudio.d.ts

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

package/dist/internal/providers/builtin/ollama.d.ts

@@ -0,0 +1,17 @@
+import type { ProviderProfile } from "../types.js";
+/**
+ * Ollama — local-first LLM runtime (ADR D182).
+ *
+ * Ships as a builtin so `Agent.create({ model: "ollama/llama3.2" })` works
+ * with zero configuration when `ollama serve` is running on the default
+ * port. `authType: "none"` signals the router to skip env-key resolution
+ * and use a placeholder credential (Ollama ignores Authorization headers
+ * on local installs).
+ *
+ * Overrides:
+ * - `OLLAMA_HOST` — replaces the default `http://localhost:11434` baseUrl
+ *   (advanced users running Ollama on a remote machine).
+ * - `OLLAMA_API_KEY` — replaces the placeholder when Ollama is behind a
+ *   reverse-proxy with auth or when using Ollama Cloud (paid tier).
+ */
+export declare const OLLAMA: ProviderProfile;

package/dist/internal/providers/builtin/openai.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderProfile } from "../types.js";
+export declare const OPENAI: ProviderProfile;

package/dist/internal/providers/builtin/openrouter.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderProfile } from "../types.js";
+export declare const OPENROUTER: ProviderProfile;

package/dist/internal/providers/builtin/vertex.d.ts

@@ -0,0 +1,27 @@
+/**
+ * GCP Vertex AI profile (Adoption Roadmap #8; ADRs D286-D302).
+ *
+ * Required peer dep: `google-auth-library` (D288). Resolves access tokens
+ * via ADC (env → gcloud → metadata server → WIF).
+ *
+ * Model IDs follow the convention `vertex/{dialect}/{model}`:
+ *   - `vertex/google/gemini-2.0-flash-001` → OpenAI-compat endpoint (D291)
+ *   - `vertex/anthropic/claude-sonnet-4-5@20250929` → :rawPredict (D292)
+ *
+ * @internal
+ */
+export declare const VERTEX: ProviderProfile;
+/**
+ * D293 absorbed: when location === "global", use `aiplatform.googleapis.com`
+ * (no `global-` prefix) — known bug `streamRawPredict` 404 at
+ * `global-aiplatform.googleapis.com` (cline#10287).
+ */
+export declare function resolveVertexBaseUrl(opts: {
+    projectId: string;
+    location: string;
+    modelDialect: "anthropic" | "gemini";
+}): string;
+/** Detect dialect from a `vertex/{dialect}/{model}` id. Default: gemini. */
+export declare function inferModelDialect(modelId: string): "anthropic" | "gemini";
+/** Strip the `vertex/{dialect}/` prefix so the raw model id is used in the URL. */
+export declare function stripVertexPrefix(modelId: string): string;

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

@@ -0,0 +1,14 @@
+/**
+ * Lazy provider discovery (T3.4, ADR D107).
+ *
+ * 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.
+ *
+ * EC-9: dynamic `import()` in Node 22 needs `file://` URL for absolute
+ * paths in ESM contexts. `pathToFileURL` handles both.
+ *
+ * @internal
+ */
+export declare function discoverProviderPlugins(): Promise<void>;

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

@@ -0,0 +1,8 @@
+/**
+ * Barrel for the provider-as-plugin system (ADRs D105-D107).
+ *
+ * @internal
+ */
+export { _resetDiscovery, discoverProviderPlugins } from "./discovery.js";
+export { _resetProvidersForTests, getProviderProfile, listProviders, registerProvider, } from "./registry.js";
+export type { ApiMode, AuthType, ProviderProfile } from "./types.js";

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

@@ -0,0 +1,12 @@
+/**
+ * Provider registry (T3.2, ADR D107).
+ *
+ * `registerProvider` is idempotent and surface-warning: re-registering
+ * a `name` logs to stderr (D107 last-writer-wins with WARN). Alias
+ * collisions also warn (EC-5).
+ *
+ * @internal
+ */
+export declare function registerProvider(profile: ProviderProfile): void;
+export declare function getProviderProfile(name: string): ProviderProfile | undefined;
+export declare function listProviders(): ProviderProfile[];

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

@@ -0,0 +1,27 @@
+/**
+ * ProviderProfile + ApiMode types (T3.1, ADR D105).
+ *
+ * Profile is **data-only** — no methods. Adding a provider is declaring an
+ * object literal; the Transport layer (D106) consumes `apiMode` to pick
+ * the HTTP dialect.
+ *
+ * @public
+ */
+export type ApiMode = "chat_completions" | "anthropic_messages" | "responses_api" | "bedrock" | "bedrock_anthropic";
+export type AuthType = "api_key" | "oauth_device_code" | "oauth_external" | "aws_sdk" | "aws_bearer" | "gcp_oauth" | "none";
+export interface ProviderProfile {
+    name: string;
+    apiMode: ApiMode;
+    aliases?: ReadonlyArray<string>;
+    displayName?: string;
+    description?: string;
+    signupUrl?: string;
+    envVars: ReadonlyArray<string>;
+    authType: AuthType;
+    baseUrl: string;
+    modelsUrl?: string;
+    hostname?: string;
+    fallbackModels: ReadonlyArray<string>;
+    extraHeaders?: Record<string, string>;
+    bodyOverrides?: Record<string, unknown>;
+}

package/dist/internal/runtime/abort-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `AbortSignal` composition helpers (Production-Readiness #5 / EC-5, ADR D324).
+ *
+ * `AbortSignal.any` is available in Node 22+ and Cloudflare Workers, but
+ * some runtime environments (Vercel Edge subset, older Bun, embedded shells)
+ * still lag. The ponyfill mirrors the spec semantics — abort on first signal,
+ * propagate `reason` — without depending on the host symbol.
+ *
+ * @internal
+ */
+/**
+ * `true` when the given (possibly undefined) signal has aborted. `undefined`
+ * signal counts as not aborted (no-signal semantics).
+ */
+export declare function isAborted(signal: AbortSignal | undefined): boolean;
+/**
+ * Extract the abort reason as an `Error` for wrapping into `AgentRunError`.
+ * Spec: `signal.reason` is `unknown` — wrap non-Error values into a generic
+ * error so callers always have a `.message` to inspect.
+ */
+export declare function abortReasonAsError(signal: AbortSignal): Error;

package/dist/internal/runtime/agent-factory-registry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tiny DI registry for `Agent.create` (T4.2 + T4.3 wiring).
+ *
+ * `LocalAgent.runUntil` and `LocalAgent.fork` need to spawn auxiliary
+ * agents via `Agent.create`. A direct import would form a cycle
+ * (`agent.ts` already imports `LocalAgent`). This module is the seam:
+ * `agent.ts` registers the factory at module init time; LocalAgent
+ * reads it on-demand.
+ *
+ * Throws if accessed before registration — should never happen because
+ * `agent.ts` evaluation always precedes `LocalAgent.runUntil()` calls
+ * (the user must call `Agent.create()` to obtain the LocalAgent first).
+ *
+ * @internal
+ */
+export type AgentCreateFn = (options: AgentOptions) => Promise<SDKAgent>;

package/dist/internal/runtime/agent-registry-store.d.ts

@@ -0,0 +1,61 @@
+export interface SerializedAgentOptions {
+    name?: string;
+    model?: {
+        id: string;
+    };
+    systemPrompt?: string;
+    local?: {
+        cwd?: string;
+        settingSources?: ReadonlyArray<string>;
+        sandboxOptions?: {
+            enabled: boolean;
+        };
+    };
+    cloud?: {
+        repos: ReadonlyArray<{
+            url: string;
+            startingRef?: string;
+        }>;
+        autoCreatePR?: boolean;
+    };
+    memory?: {
+        enabled: boolean;
+        namespace?: string;
+        userId?: string;
+        scope?: string;
+        index?: {
+            tools?: boolean;
+            backend?: string;
+            embedding?: {
+                provider: string;
+                model?: string;
+            };
+        };
+        activeRecall?: Record<string, unknown>;
+    };
+    skills?: {
+        enabled?: ReadonlyArray<string>;
+    };
+    plugins?: {
+        enabled?: ReadonlyArray<string>;
+    };
+    context?: {
+        manager?: string;
+        maxTokens?: number;
+    };
+    providers?: {
+        routes: ReadonlyArray<{
+            capability: string;
+            provider: string;
+            model?: string;
+        }>;
+        fallback?: ReadonlyArray<string>;
+    };
+    agents?: Record<string, {
+        description: string;
+        prompt: string;
+        model?: {
+            id: string;
+        } | "inherit";
+    }>;
+}

package/dist/internal/runtime/agent-registry.d.ts

@@ -0,0 +1,34 @@
+import type { AgentOptions, ModelSelection } from "../../types/agent.js";
+export interface RegisteredAgent {
+    agentId: string;
+    runtime: AgentRuntime;
+    name?: string;
+    summary?: string;
+    model?: ModelSelection;
+    createdAt: number;
+    lastModified: number;
+    archived: boolean;
+    options: AgentOptions;
+    /** Local workspace cwd; only set when runtime is local. Also used as the
+     * persistence routing key (cloud agents default to `process.cwd()`). */
+    cwd?: string;
+    /** Cloud repo URLs; only set when runtime is cloud. */
+    repos?: string[];
+    /** Optional explicit status reported via SDKAgentInfo.status. */
+    status?: "running" | "finished" | "error";
+    /**
+     * EC-3 (ADR D325): marker set at create-time when
+     * `AgentOptions.conversationStorage` was non-undefined. `Agent.resume`
+     * checks this flag — if `true` AND the caller did not pass
+     * `conversationStorage` again, throws `ConfigurationError(code:
+     * "conversation_storage_required")` instead of silently falling back to
+     * the FS adapter (which would lose Postgres/Redis history).
+     */
+    requiresCustomStorage?: boolean;
+}
+export declare function registerAgent(agent: RegisteredAgent): void;
+export declare function getRegisteredAgent(agentId: string): RegisteredAgent | undefined;
+export declare function listRegisteredAgents(runtime?: AgentRuntime): RegisteredAgent[];
+export declare function updateRegisteredAgent(agentId: string, update: Partial<RegisteredAgent>): RegisteredAgent | undefined;
+export declare function removeRegisteredAgent(agentId: string): boolean;
+export declare function clearAgentRegistry(): void;

package/dist/internal/runtime/agent-session-store.d.ts

@@ -0,0 +1,3 @@
+import type { SessionMessage } from "./agent-session.js";
+export declare function sessionFilePath(cwd: string, agentId: string): string;
+export declare function readSessionFile(cwd: string, agentId: string): Promise<SessionMessage[]>;

package/dist/internal/runtime/agent-session.d.ts

@@ -0,0 +1,2 @@
+export declare function getSessionMessages(agentId: string): SessionMessage[];
+export declare function clearSession(agentId: string): void;

package/dist/internal/runtime/async-local-storage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-fork tool whitelist via `AsyncLocalStorage` (ADR D111).
+ *
+ * Forked agents (background review, curator, judge) need a tool subset
+ * distinct from the parent's. A global mutable `let _whitelist` would
+ * corrupt state when two forks run in parallel. `AsyncLocalStorage`
+ * propagates the whitelist through the async chain so each fork sees its
+ * own — no cross-fork bleed.
+ *
+ * Outside a `withToolWhitelist(...)` scope, `currentToolWhitelist()`
+ * returns `undefined` and `checkToolWhitelist` allows every tool — the
+ * parent agent is unaffected.
+ *
+ * Wire site: `internal/agent-loop/tool-dispatch.ts:dispatchSingleCall`
+ * calls `checkToolWhitelist` after the repair middleware and before
+ * `tools.find`.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/runtime/async-semaphore.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Async-aware counting semaphore (ADR D135).
+ *
+ * N-permit gate for cooperative concurrency control inside a single
+ * Node process. Used by `Agent.batch` to bound parallel agent count
+ * without pulling in `p-limit` or `p-queue` (~30 LoC in-house).
+ *
+ * Contract: `acquire()` returns a release function. Caller MUST call
+ * release exactly once when done — typically in a `finally` block.
+ * Release is idempotent (multiple calls are no-ops after the first)
+ * for defense against caller bugs, but leaking the release function
+ * permanently consumes one permit (EC-G — caller responsibility).
+ *
+ * @internal
+ */
+export interface AsyncSemaphore {
+    /** Acquire a permit. Returns the release function (call once). */
+    acquire(): Promise<() => void>;
+    /** Permits currently held in flight. */
+    inFlight(): number;
+    /** Total: in-flight + queued waiters. */
+    pending(): number;
+}
+export declare function createSemaphore(permits: number): AsyncSemaphore;

package/dist/internal/runtime/budget.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Iteration budget for the agent loop (T2.1, ADRs D90-D91).
+ *
+ * Tracks remaining iterations + compression attempts + grace-call usage.
+ * Caps prevent the 4 compression death spirals Hermes shipped:
+ *   - v0.4 #1723: `compression_attempts` never reset
+ *   - v0.7 #4750: compression triggers → fails → triggers again
+ *   - v0.11 #10065: stale agent timeout, empty response after tools
+ *   - v0.11 #10472: empty-tools after tools, premature loop exit
+ *
+ * Default: max 8 iterations, max 3 compressions per session, 1 grace call.
+ *
+ * NOTE on caller-supplied huge maxIterations (EC-12): `Number.MAX_SAFE_INTEGER`
+ * is honored — caller is responsible for picking a reasonable cap. Recommended
+ * ≤32 for production workloads.
+ *
+ * NOTE on per-send reset (EC-14): each `Agent.send` should construct a fresh
+ * `IterationBudget`. This is intentional — every send is its own iteration
+ * round, not a long-running budget shared across sends.
+ *
+ * @internal
+ */
+export declare class CompressionExhaustedError extends Error {
+    readonly name: string;
+}
+export declare class CompressionIneffectiveError extends Error {
+    readonly name: string;
+}
+export interface IterationBudgetOptions {
+    /** Total iterations before grace call. Default 8. */
+    maxIterations?: number;
+    /** Max compression attempts per session (D91). Default 3. */
+    maxCompressions?: number;
+    /** When true (default), one final iteration is allowed after budget exhausted. */
+    allowGraceCall?: boolean;
+}

package/dist/internal/runtime/cloud-agent.d.ts

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

package/dist/internal/runtime/cloud-config-serializer.d.ts

@@ -0,0 +1,3 @@
+import type { AgentOptions } from "../../types/agent.js";
+import type { CloudAgentPayload } from "./cloud-payload-types.js";
+export declare function serializeCloudAgentConfig(options: AgentOptions): CloudAgentPayload;