@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/{sdk-agent-D8qJVkuV.d.ts → sdk-agent-BOiKqOgL.d.cts}

@@ -1,7 +1,10 @@
-import { M as ModelSelection, ad as SDKUserMessage, af as SendOptions, b as Run, G as GenerateOptions, n as GenerateRunResult, $ as RunToCompletionOptions, a0 as RunToCompletionResult, S as SDKMessage, am as StreamToCompletionResult } from './run-BYSHf58D.js';
+import { M as ModelSelection, aa as SDKUserMessage, ac as SendOptions, b as Run, G as GenerateOptions, m as GenerateRunResult, Y as RunToCompletionOptions, Z as RunToCompletionResult, S as SDKMessage, aj as StreamToCompletionResult } from './run-CTAdRU3U.cjs';
 import * as zod from 'zod';
 
 /**
+ * Owner: `internal/local-agent/` (2 of 4 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
  *
  * The plugin extension point `{ kind: "memory" }` (ADR D98) declares a
@@ -189,6 +192,9 @@ interface AgentMemory {
 }
 
 /**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Context manager backend.
  *
  * - `"file"` — Read `.theokit/context.json` from the workspace (local) or the
@@ -283,6 +289,126 @@ interface SDKContextManager {
 }
 
 /**
+ * Owner: `src/` (4 of 9 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * Capability slot a provider can fulfill.
+ *
+ * @public
+ */
+type ProviderCapability = "chat" | "web_search" | "image" | "embedding";
+/**
+ * A single user-declared routing rule. Maps a capability to a provider, and
+ * optionally pins a specific model.
+ *
+ * @public
+ */
+interface ProviderRoute {
+    capability: ProviderCapability;
+    provider: string;
+    model?: string;
+    /**
+     * Opt-in leaked-dialect safe-parse for this route's provider (theokit#58
+     * follow-up). When `true`, a `chat_completions` finish that carries ZERO
+     * native `tool_calls` has its assistant text scanned for the Hermes
+     * `<function=…></tool_call>` dialect, and any recovered calls are surfaced as
+     * real `tool_calls` so the loop executes them — for models (qwen3-coder via
+     * OpenRouter) that intermittently leak tool calls as text. Default `false`;
+     * fail-open (a partial/unclosed block never fabricates a call). Scoped to the
+     * resolved chat chain, so a non-leaking route is unaffected.
+     */
+    extractToolCallsFromContent?: boolean;
+}
+/**
+ * Provider routing configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.providers}.
+ *
+ * @public
+ */
+interface ProviderRoutingSettings {
+    /** Explicit `{ capability → provider }` map. First match wins per capability. */
+    routes: ProviderRoute[];
+    /** Provider names to try in order when a route has no provider available. */
+    fallback?: string[];
+    /**
+     * Multiple API keys per provider for same-provider key rotation
+     * (credential pool — ADRs D123-D133). When a key hits HTTP 429, 402,
+     * or 401, the SDK rotates to the next entry transparently before
+     * falling back to a different provider.
+     *
+     * Example:
+     * ```ts
+     * apiKeys: { openrouter: ["sk-or-...", "sk-or-..."], anthropic: ["..."] }
+     * ```
+     *
+     * Empty arrays and empty strings are filtered out. If a provider has
+     * exactly 1 effective key, the pool is transparent (no rotation behavior).
+     *
+     * Conflicts with the single-key shape `AgentOptions.apiKey: "..."` —
+     * use one OR the other, not both.
+     *
+     * @public
+     */
+    apiKeys?: Record<string, string[]>;
+    /**
+     * Rotation strategy per provider for the credential pool. Default is
+     * `"fill_first"` (use entries[0] until exhausted). Only consulted when
+     * `apiKeys[provider]` has ≥2 entries.
+     *
+     * @public
+     */
+    credentialPoolStrategy?: Record<string, "fill_first" | "round_robin" | "least_used" | "random">;
+}
+/**
+ * Plugins configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.plugins}.
+ *
+ * @public
+ */
+interface PluginsSettings {
+    /** Plugin names to enable. Plugin discovery is plugin-provider specific. */
+    enabled?: string[];
+}
+/**
+ * Resolved routing decision returned by `agent.providers.routes()`. Public and
+ * secret-free by design — safe to log.
+ *
+ * @public
+ */
+interface ResolvedProviderRoute {
+    capability: string;
+    provider: string;
+    model?: string;
+    /** Why the runtime picked this provider (e.g. `"explicit-model-provider"`). */
+    reason: string;
+}
+/**
+ * Public providers manager handle exposed as `agent.providers`.
+ *
+ * @public
+ */
+interface SDKProvidersManager {
+    /** Inspect which provider serves each capability for this agent. */
+    routes(): Promise<ResolvedProviderRoute[]>;
+}
+/**
+ * Provider catalog entry returned by `Theokit.providers.list()`.
+ *
+ * @public
+ */
+interface SDKProvider {
+    name: string;
+    displayName: string;
+    capabilities: string[];
+    isAvailable: boolean;
+    /** JSON Schema describing the env vars / fields needed to enable this provider. */
+    setupSchema: object;
+}
+
+/**
+ * Owner: `internal/runtime/lifecycle/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Fork primitive public type contracts (T1.2, ADRs D110-D114).
  *
  * Extracted into a leaf type module (arch-review ADR 0001) so the public
@@ -333,6 +459,9 @@ interface ForkResult {
 }
 
 /**
+ * Owner: `internal/judge/` (3 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * M80 — the terminal verdicts a judge can return.
  *
  * `"blocked"` was added here in this milestone. `GoalResult.status` already carried it, but the
@@ -474,120 +603,6 @@ interface GoalOptions {
     signal?: AbortSignal;
 }
 
-/**
- * Capability slot a provider can fulfill.
- *
- * @public
- */
-type ProviderCapability = "chat" | "web_search" | "image" | "embedding";
-/**
- * A single user-declared routing rule. Maps a capability to a provider, and
- * optionally pins a specific model.
- *
- * @public
- */
-interface ProviderRoute {
-    capability: ProviderCapability;
-    provider: string;
-    model?: string;
-    /**
-     * Opt-in leaked-dialect safe-parse for this route's provider (theokit#58
-     * follow-up). When `true`, a `chat_completions` finish that carries ZERO
-     * native `tool_calls` has its assistant text scanned for the Hermes
-     * `<function=…></tool_call>` dialect, and any recovered calls are surfaced as
-     * real `tool_calls` so the loop executes them — for models (qwen3-coder via
-     * OpenRouter) that intermittently leak tool calls as text. Default `false`;
-     * fail-open (a partial/unclosed block never fabricates a call). Scoped to the
-     * resolved chat chain, so a non-leaking route is unaffected.
-     */
-    extractToolCallsFromContent?: boolean;
-}
-/**
- * Provider routing configuration accepted by `Agent.create()` via
- * {@link AgentOptions.providers}.
- *
- * @public
- */
-interface ProviderRoutingSettings {
-    /** Explicit `{ capability → provider }` map. First match wins per capability. */
-    routes: ProviderRoute[];
-    /** Provider names to try in order when a route has no provider available. */
-    fallback?: string[];
-    /**
-     * Multiple API keys per provider for same-provider key rotation
-     * (credential pool — ADRs D123-D133). When a key hits HTTP 429, 402,
-     * or 401, the SDK rotates to the next entry transparently before
-     * falling back to a different provider.
-     *
-     * Example:
-     * ```ts
-     * apiKeys: { openrouter: ["sk-or-...", "sk-or-..."], anthropic: ["..."] }
-     * ```
-     *
-     * Empty arrays and empty strings are filtered out. If a provider has
-     * exactly 1 effective key, the pool is transparent (no rotation behavior).
-     *
-     * Conflicts with the single-key shape `AgentOptions.apiKey: "..."` —
-     * use one OR the other, not both.
-     *
-     * @public
-     */
-    apiKeys?: Record<string, string[]>;
-    /**
-     * Rotation strategy per provider for the credential pool. Default is
-     * `"fill_first"` (use entries[0] until exhausted). Only consulted when
-     * `apiKeys[provider]` has ≥2 entries.
-     *
-     * @public
-     */
-    credentialPoolStrategy?: Record<string, "fill_first" | "round_robin" | "least_used" | "random">;
-}
-/**
- * Plugins configuration accepted by `Agent.create()` via
- * {@link AgentOptions.plugins}.
- *
- * @public
- */
-interface PluginsSettings {
-    /** Plugin names to enable. Plugin discovery is plugin-provider specific. */
-    enabled?: string[];
-}
-/**
- * Resolved routing decision returned by `agent.providers.routes()`. Public and
- * secret-free by design — safe to log.
- *
- * @public
- */
-interface ResolvedProviderRoute {
-    capability: string;
-    provider: string;
-    model?: string;
-    /** Why the runtime picked this provider (e.g. `"explicit-model-provider"`). */
-    reason: string;
-}
-/**
- * Public providers manager handle exposed as `agent.providers`.
- *
- * @public
- */
-interface SDKProvidersManager {
-    /** Inspect which provider serves each capability for this agent. */
-    routes(): Promise<ResolvedProviderRoute[]>;
-}
-/**
- * Provider catalog entry returned by `Theokit.providers.list()`.
- *
- * @public
- */
-interface SDKProvider {
-    name: string;
-    displayName: string;
-    capabilities: string[];
-    isAvailable: boolean;
-    /** JSON Schema describing the env vars / fields needed to enable this provider. */
-    setupSchema: object;
-}
-
 /**
  * Public skill metadata exposed to the system-prompt resolver. Mirrors the
  * shape returned by `agent.skills.list()` — name + description only, never
@@ -598,10 +613,27 @@ interface SDKProvider {
 interface SystemPromptSkillRef {
     name: string;
     description: string;
+    /**
+     * Where this skill came from: the absolute path to its `SKILL.md` for a skill read from disk,
+     * or the synthetic `inline://<name>` marker `createSkill` stamps on a code-defined one (see
+     * `create-skill.ts`) — there is no third case, so this is populated for every skill `list()`
+     * returns.
+     *
+     * It is the ORIGIN and NOT the body: `list()` stays lean by contract, and a skill's instructions
+     * are reachable only through {@link SDKAgentSkills.get}. What this adds is the answer to
+     * usetheokit/theokit-sdk#524's visibility question — which root a skill came from, so a listing
+     * can show that one arrived from `.claude/skills/` rather than the project's own directory, or
+     * that it was never on disk at all.
+     *
+     * Typed optional rather than required because {@link SystemPromptSkillRef} is the shape any
+     * future skill producer returns, and this SDK should not assert every one of them can name an
+     * origin.
+     */
+    source?: string;
 }
 /**
  * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
- * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * {@link SystemPromptSkillRef}, which carries metadata only, this carries the full
  * `instructions` — read from the SKILL.md for filesystem skills or the inline
  * `createSkill` body. @public
  */
@@ -645,6 +677,16 @@ interface SDKAgentSkills {
 interface SDKPluginMetadata {
     name: string;
     description?: string;
+    /**
+     * Absolute path the plugin manifest was read from.
+     *
+     * The runtime has ALWAYS returned this — `agent.plugins.list()` hands back the internal
+     * `PluginMetadata`, whose own docblock says it carries provenance "so callers can audit where the
+     * plugin came from". This type simply did not declare it, so the caller received the field and
+     * the compiler denied it existed. Declaring it is what makes the audit usetheokit/theokit-sdk#524
+     * asks for reachable in typed code.
+     */
+    source?: string;
 }
 /**
  * Public plugin listing handle exposed as `agent.plugins`. Populated when
@@ -666,6 +708,16 @@ interface SDKArtifact {
     sizeBytes: number;
     updatedAt: string;
 }
+/**
+ * An operation a consumer may ask an {@link SDKAgent} about via `supports()`.
+ *
+ * Deliberately the members whose availability DIFFERS between runtimes, plus the core ones a caller
+ * may want to assert positively. A union rather than `string` so a typo is a compile error instead
+ * of a silent `false`.
+ *
+ * @public
+ */
+type AgentOperation = "send" | "generate" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "runToCompletion" | "streamToCompletion" | "usePersonality" | "invalidateCache";
 /**
  * Handle returned by `Agent.create()` and `Agent.resume()`.
  *
@@ -719,6 +771,34 @@ interface SDKAgent {
      * idempotent across both surfaces.
      */
     [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Which operations this agent's runtime actually performs.
+     *
+     * `SDKAgent` is one handle over two runtimes that do not offer the same operations, and the type
+     * does not model the difference: `downloadArtifact` is a REQUIRED member that rejects for every
+     * input on a local agent, and five optional members are present-but-throwing on a cloud one, so
+     * `typeof agent.fork === "function"` is true and calling it throws. Neither requiredness nor
+     * optionality expresses "exists here, not there".
+     *
+     * Ask before calling. Mirrors `Run.supports(op)` / `Run.unsupportedReason(op)`, which solved the
+     * same problem one layer down over the `RunOperation` union.
+     *
+     * This is a MITIGATION. The structural fix is to split this interface into a common core plus
+     * `LocalCapableAgent` / `CloudCapableAgent`, so the compiler refuses the call instead of the
+     * runtime and a consumer narrows once instead of asking per call. That is breaking on a published
+     * surface and is deliberately not done here.
+     *
+     * @public
+     */
+    supports(operation: AgentOperation): boolean;
+    /**
+     * Human-readable reason `supports(operation)` returned `false`, or `undefined` when it returned
+     * `true`. The message names the runtime, so an operator reading a log knows which half of the
+     * union they are holding.
+     *
+     * @public
+     */
+    unsupportedReason(operation: AgentOperation): string | undefined;
     /** Cloud-only. Local returns an empty array. */
     listArtifacts(): Promise<SDKArtifact[]>;
     /** Cloud-only. Local throws `UnsupportedRunOperationError`. */
@@ -857,4 +937,4 @@ interface InvalidateCacheOptions {
     applyNow?: boolean;
 }
 
-export type { AgentMemory as A, SDKProvidersManager as B, ContextSettings as C, SystemPromptSkillRef as D, GoalOptions as G, InvalidateCacheOptions as I, JudgeResult as J, MemoryId as M, ProviderRoutingSettings as P, ResolvedProviderRoute as R, SDKAgent as S, Verdict as V, PluginsSettings as a, GoalEvent as b, GoalResult as c, SDKProvider as d, ContextBudget as e, ContextManagerKind as f, ContextSnapshot as g, ContextSource as h, ContextSourceStatus as i, MemoryAdapter as j, MemoryAdapterCapabilities as k, MemoryContext as l, MemoryFact as m, MemoryRevision as n, MemoryToolSchema as o, MemoryTurnMessage as p, PersonalityPreset as q, ProviderCapability as r, ProviderRoute as s, RunUntilIterator as t, SDKAgentPlugins as u, SDKAgentSkillDetail as v, SDKAgentSkills as w, SDKArtifact as x, SDKContextManager as y, SDKPluginMetadata as z };
+export type { AgentMemory as A, SDKPluginMetadata as B, ContextSettings as C, SDKProvidersManager as D, SystemPromptSkillRef as E, GoalOptions as G, InvalidateCacheOptions as I, JudgeResult as J, MemoryId as M, ProviderRoutingSettings as P, ResolvedProviderRoute as R, SDKAgent as S, Verdict as V, PluginsSettings as a, GoalEvent as b, GoalResult as c, SDKProvider as d, AgentOperation as e, ContextBudget as f, ContextManagerKind as g, ContextSnapshot as h, ContextSource as i, ContextSourceStatus as j, MemoryAdapter as k, MemoryAdapterCapabilities as l, MemoryContext as m, MemoryFact as n, MemoryRevision as o, MemoryToolSchema as p, MemoryTurnMessage as q, PersonalityPreset as r, ProviderCapability as s, ProviderRoute as t, RunUntilIterator as u, SDKAgentPlugins as v, SDKAgentSkillDetail as w, SDKAgentSkills as x, SDKArtifact as y, SDKContextManager as z };