@theokit/sdk 2.20.0 → 2.22.0

package/dist/a2a/subagent.d.cts

@@ -5,9 +5,53 @@
  * invoked by the LLM, creates a child agent and sends the input as a
  * message. EC-2: delegation depth tracked to prevent infinite recursion.
  *
+ * SE10 — the handler forwards the parent run's `AbortSignal` to the child.
+ * SE11 — optional `onDelegationStart` / `onDelegationComplete` lifecycle hooks
+ * let the caller reject, rewrite, observe, or annotate a delegation.
+ *
  * @public
  */
-import type { CustomTool } from "../types/agent.js";
+import type { CustomTool, ToolContextMessage } from "../types/agent.js";
+/** Arguments passed to {@link SubAgentSpec.messageFilter} (SE12). */
+export interface MessageFilterArgs {
+    /** The supervisor transcript (read-only text projection) available to this delegation. */
+    messages: readonly ToolContextMessage[];
+    /** The prompt about to be delegated (after any `onDelegationStart` rewrite). */
+    input: string;
+    /** The subagent's name. */
+    name: string;
+}
+/** Context passed to {@link SubAgentSpec.onDelegationStart} before the child runs. */
+export interface DelegationStartContext {
+    input: string;
+    name: string;
+}
+/**
+ * Decision returned from {@link SubAgentSpec.onDelegationStart}. Discriminated on
+ * `proceed` so a rejection (`proceed: false` + `rejectionReason`) and an approval
+ * (`modifiedInput`) cannot be mixed into one nonsensical object.
+ */
+export type DelegationStartDecision = {
+    proceed: false;
+    rejectionReason?: string;
+} | {
+    proceed?: true;
+    modifiedInput?: string;
+};
+/** Context passed to {@link SubAgentSpec.onDelegationComplete} after the child settles. */
+export interface DelegationCompleteContext {
+    input: string;
+    name: string;
+    /** The child's text result (present on success). */
+    result?: string;
+    /** The error the child threw (present on failure); the error is still re-thrown. */
+    error?: unknown;
+}
+/** Decision returned from {@link SubAgentSpec.onDelegationComplete}. */
+export interface DelegationCompleteDecision {
+    /** Appended to the child's result string. */
+    feedback?: string;
+}
 export interface SubAgentSpec {
     name: string;
     description: string;
@@ -15,6 +59,31 @@ export interface SubAgentSpec {
     model?: string;
     tools?: CustomTool[];
     maxDelegationDepth?: number;
+    /**
+     * SE11 — called before the supervisor delegates. Return `{ proceed: false }`
+     * to reject (the child never runs and `rejectionReason` becomes the tool
+     * result), or `{ modifiedInput }` to rewrite the delegated prompt. A throwing
+     * hook surfaces (never silently swallowed).
+     */
+    onDelegationStart?: (ctx: DelegationStartContext) => DelegationStartDecision | undefined | Promise<DelegationStartDecision | undefined>;
+    /**
+     * SE11 — called after the delegation settles. On success `ctx.result` is set
+     * and an optional `{ feedback }` is appended to it. On failure `ctx.error` is
+     * set and the original error is ALWAYS re-thrown after this hook runs — a throw
+     * from this hook on the error path is suppressed so it cannot mask the
+     * delegation's real failure (on the success path a throw does propagate).
+     */
+    onDelegationComplete?: (ctx: DelegationCompleteContext) => DelegationCompleteDecision | undefined | Promise<DelegationCompleteDecision | undefined>;
+    /**
+     * SE12 — opt-in parent-context forwarding. When set, the supervisor transcript
+     * (`ctx.messages`, a read-only text projection) is passed to this filter and the
+     * returned subset is forwarded to the child as a role-tagged context preamble
+     * prepended to the delegated input. When ABSENT the child runs input-only —
+     * memory isolation stays the default. A filter returning `[]` forwards nothing.
+     * A throwing filter propagates (fail-fast, never swallowed — same contract as
+     * `onDelegationStart`); the delegation surfaces as a tool error.
+     */
+    messageFilter?: (args: MessageFilterArgs) => readonly ToolContextMessage[];
 }
 export declare class MaxDelegationDepthError extends Error {
     readonly currentDepth: number;

package/dist/a2a/subagent.d.ts

@@ -5,9 +5,53 @@
  * invoked by the LLM, creates a child agent and sends the input as a
  * message. EC-2: delegation depth tracked to prevent infinite recursion.
  *
+ * SE10 — the handler forwards the parent run's `AbortSignal` to the child.
+ * SE11 — optional `onDelegationStart` / `onDelegationComplete` lifecycle hooks
+ * let the caller reject, rewrite, observe, or annotate a delegation.
+ *
  * @public
  */
-import type { CustomTool } from "../types/agent.js";
+import type { CustomTool, ToolContextMessage } from "../types/agent.js";
+/** Arguments passed to {@link SubAgentSpec.messageFilter} (SE12). */
+export interface MessageFilterArgs {
+    /** The supervisor transcript (read-only text projection) available to this delegation. */
+    messages: readonly ToolContextMessage[];
+    /** The prompt about to be delegated (after any `onDelegationStart` rewrite). */
+    input: string;
+    /** The subagent's name. */
+    name: string;
+}
+/** Context passed to {@link SubAgentSpec.onDelegationStart} before the child runs. */
+export interface DelegationStartContext {
+    input: string;
+    name: string;
+}
+/**
+ * Decision returned from {@link SubAgentSpec.onDelegationStart}. Discriminated on
+ * `proceed` so a rejection (`proceed: false` + `rejectionReason`) and an approval
+ * (`modifiedInput`) cannot be mixed into one nonsensical object.
+ */
+export type DelegationStartDecision = {
+    proceed: false;
+    rejectionReason?: string;
+} | {
+    proceed?: true;
+    modifiedInput?: string;
+};
+/** Context passed to {@link SubAgentSpec.onDelegationComplete} after the child settles. */
+export interface DelegationCompleteContext {
+    input: string;
+    name: string;
+    /** The child's text result (present on success). */
+    result?: string;
+    /** The error the child threw (present on failure); the error is still re-thrown. */
+    error?: unknown;
+}
+/** Decision returned from {@link SubAgentSpec.onDelegationComplete}. */
+export interface DelegationCompleteDecision {
+    /** Appended to the child's result string. */
+    feedback?: string;
+}
 export interface SubAgentSpec {
     name: string;
     description: string;
@@ -15,6 +59,31 @@ export interface SubAgentSpec {
     model?: string;
     tools?: CustomTool[];
     maxDelegationDepth?: number;
+    /**
+     * SE11 — called before the supervisor delegates. Return `{ proceed: false }`
+     * to reject (the child never runs and `rejectionReason` becomes the tool
+     * result), or `{ modifiedInput }` to rewrite the delegated prompt. A throwing
+     * hook surfaces (never silently swallowed).
+     */
+    onDelegationStart?: (ctx: DelegationStartContext) => DelegationStartDecision | undefined | Promise<DelegationStartDecision | undefined>;
+    /**
+     * SE11 — called after the delegation settles. On success `ctx.result` is set
+     * and an optional `{ feedback }` is appended to it. On failure `ctx.error` is
+     * set and the original error is ALWAYS re-thrown after this hook runs — a throw
+     * from this hook on the error path is suppressed so it cannot mask the
+     * delegation's real failure (on the success path a throw does propagate).
+     */
+    onDelegationComplete?: (ctx: DelegationCompleteContext) => DelegationCompleteDecision | undefined | Promise<DelegationCompleteDecision | undefined>;
+    /**
+     * SE12 — opt-in parent-context forwarding. When set, the supervisor transcript
+     * (`ctx.messages`, a read-only text projection) is passed to this filter and the
+     * returned subset is forwarded to the child as a role-tagged context preamble
+     * prepended to the delegated input. When ABSENT the child runs input-only —
+     * memory isolation stays the default. A filter returning `[]` forwards nothing.
+     * A throwing filter propagates (fail-fast, never swallowed — same contract as
+     * `onDelegationStart`); the delegation surfaces as a tool error.
+     */
+    messageFilter?: (args: MessageFilterArgs) => readonly ToolContextMessage[];
 }
 export declare class MaxDelegationDepthError extends Error {
     readonly currentDepth: number;

package/dist/a2a/types.d.cts

@@ -2,11 +2,18 @@
  * A2A (Agent-to-Agent) communication types (T20.1, ADR D453).
  * @public
  */
+import type { MessageOrigin } from "../types/run.js";
 export interface A2AMessage<T = unknown> {
     type: string;
     payload: T;
     from: string;
     to: string;
     timestamp: number;
+    /**
+     * SE3 — provenance projection of the sender address: `{ kind: "peer", from }`.
+     * A thin view over `from` (not a parallel system), so a receiver that turns an
+     * a2a message into a turn can forward it via `SendOptions.origin`.
+     */
+    origin?: MessageOrigin;
 }
 export type MessageHandler<T = unknown> = (message: A2AMessage<T>) => undefined | unknown | Promise<undefined | unknown>;

package/dist/a2a/types.d.ts

@@ -2,11 +2,18 @@
  * A2A (Agent-to-Agent) communication types (T20.1, ADR D453).
  * @public
  */
+import type { MessageOrigin } from "../types/run.js";
 export interface A2AMessage<T = unknown> {
     type: string;
     payload: T;
     from: string;
     to: string;
     timestamp: number;
+    /**
+     * SE3 — provenance projection of the sender address: `{ kind: "peer", from }`.
+     * A thin view over `from` (not a parallel system), so a receiver that turns an
+     * a2a message into a turn can forward it via `SendOptions.origin`.
+     */
+    origin?: MessageOrigin;
 }
 export type MessageHandler<T = unknown> = (message: A2AMessage<T>) => undefined | unknown | Promise<undefined | unknown>;

package/dist/agent-builder.d.ts

@@ -18,7 +18,8 @@ export declare class AgentBuilder {
     private opts;
     private readonly deps;
     constructor(deps?: AgentBuilderDeps);
-    model(m: ModelSelection): this;
+    /** SE8 — accepts a bare-string id shorthand (`"openai/gpt-4o-mini"`) or a {@link ModelSelection}. */
+    model(m: string | ModelSelection): this;
     apiKey(k: string): this;
     name(n: string): this;
     systemPrompt(p: string | SystemPromptResolver): this;

package/dist/agent-generate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SE9 — integrated structured output: `agent.generate(input, { output })` runs the
+ * agent's NORMAL tool loop (the user's tools run first) and then coerces the final
+ * answer into a Zod schema, returning a validated, inferred-typed object.
+ *
+ * This is SUGAR over `generateObject` (ADR D33) — it does NOT fork the
+ * synthetic-forced-tool machinery. Phase 1 is the user's own `agent.send()` run;
+ * phase 2 reuses `generateObjectImpl` over the run's final answer.
+ *
+ * @public
+ */
+export type { GenerateOptions, GenerateRunResult } from "./types/run.js";

package/dist/client/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/client/theokit-client.ts"],"names":[],"mappings":";;;AAYO,IAAM,gBAAN,MAAoB;AAAA,EACR,QAAA;AAAA,EACA,SAAA;AAAA,EACA,QAAA;AAAA,EAEjB,YAAY,IAAA,EAAqB;AAC/B,IAAA,IAAA,CAAK,QAAA,GAAW,IAAA,CAAK,OAAA,CAAQ,OAAA,CAAQ,OAAO,EAAE,CAAA;AAC9C,IAAA,IAAA,CAAK,SAAA,GAAY,KAAK,QAAA,IAAY,QAAA;AAClC,IAAA,IAAA,CAAK,QAAA,GAAW,IAAA,CAAK,OAAA,IAAW,EAAC;AAAA,EACnC;AAAA,EAEA,MAAM,KAAK,KAAA,EAAsC;AAC/C,IAAA,MAAM,MAAM,CAAA,EAAG,IAAA,CAAK,QAAQ,CAAA,EAAG,KAAK,SAAS,CAAA,KAAA,CAAA;AAC7C,IAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,GAAA,EAAK;AAAA,MAChC,MAAA,EAAQ,MAAA;AAAA,MACR,OAAA,EAAS;AAAA,QACP,cAAA,EAAgB,kBAAA;AAAA,QAChB,GAAG,IAAA,CAAK;AAAA,OACV;AAAA,MACA,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,EAAE,OAAO;AAAA,KAC/B,CAAA;AAED,IAAA,IAAI,CAAC,SAAS,EAAA,EAAI;AAChB,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,uCAAA,EAA0C,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AAAA,IAC7E;AAEA,IAAA,OAAQ,MAAM,SAAS,IAAA,EAAK;AAAA,EAC9B;AAAA;AAAA,EAGA,OAAO,OAAO,KAAA,EAAwD;AACpE,IAAA,MAAM,GAAA,GAAM,CAAA,EAAG,IAAA,CAAK,QAAQ,CAAA,EAAG,KAAK,SAAS,CAAA,cAAA,EAAiB,kBAAA,CAAmB,KAAK,CAAC,CAAA,CAAA;AACvF,IAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,GAAA,EAAK;AAAA,MAChC,OAAA,EAAS;AAAA,QACP,MAAA,EAAQ,mBAAA;AAAA,QACR,GAAG,IAAA,CAAK;AAAA;AACV,KACD,CAAA;AAED,IAAA,IAAI,CAAC,SAAS,EAAA,EAAI;AAChB,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,yCAAA,EAA4C,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AAAA,IAC/E;AAEA,IAAA,MAAM,MAAA,GAAS,QAAA,CAAS,IAAA,EAAM,SAAA,EAAU;AACxC,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,MAAM,IAAI,MAAM,8CAA8C,CAAA;AAAA,IAChE;AAEA,IAAA,MAAM,OAAA,GAAU,IAAI,WAAA,EAAY;AAChC,IAAA,IAAI,MAAA,GAAS,EAAA;AAEb,IAAA,IAAI;AAEF,MAAA,OAAO,IAAA,EAAM;AACX,QAAA,MAAM,EAAE,IAAA,EAAM,KAAA,EAAM,GAAI,MAAM,OAAO,IAAA,EAAK;AAC1C,QAAA,IAAI,IAAA,EAAM;AAEV,QAAA,MAAA,IAAU,QAAQ,MAAA,CAAO,KAAA,EAAO,EAAE,MAAA,EAAQ,MAAM,CAAA;AAChD,QAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,IAAI,CAAA;AAC/B,QAAA,MAAA,GAAS,KAAA,CAAM,KAAI,IAAK,EAAA;AAGxB,QAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,UAAA,MAAM,OAAA,GAAU,KAAK,IAAA,EAAK;AAC1B,UAAA,IAAI,OAAA,CAAQ,UAAA,CAAW,QAAQ,CAAA,EAAG;AAChC,YAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,KAAA,CAAM,CAAC,CAAA;AAC5B,YAAA,IAAI,SAAS,QAAA,EAAU;AACvB,YAAA,IAAI;AACF,cAAA,MAAM,IAAA,CAAK,MAAM,IAAI,CAAA;AAAA,YACvB,CAAA,CAAA,MAAQ;AAAA,YAER;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF,CAAA,SAAE;AACA,MAAA,MAAA,CAAO,WAAA,EAAY;AAAA,IACrB;AAAA,EACF;AACF","file":"index.cjs","sourcesContent":["/**\n * TheoKitClient — browser-safe client for consuming server adapter endpoints\n * (T20.2, ADR D454).\n *\n * Zero Node dependencies. Uses native fetch + manual SSE parsing.\n * Consumes the same HTTP contract as server adapters (POST /send, GET /stream).\n *\n * @public\n */\n\nimport type { ClientOptions, SendResponse, StreamEvent } from \"./types.js\";\n\nexport class TheoKitClient {\n  private readonly _baseUrl: string;\n  private readonly _basePath: string;\n  private readonly _headers: Record<string, string>;\n\n  constructor(opts: ClientOptions) {\n    this._baseUrl = opts.baseUrl.replace(/\\/$/, \"\");\n    this._basePath = opts.basePath ?? \"/agent\";\n    this._headers = opts.headers ?? {};\n  }\n\n  async send(input: string): Promise<SendResponse> {\n    const url = `${this._baseUrl}${this._basePath}/send`;\n    const response = await fetch(url, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...this._headers,\n      },\n      body: JSON.stringify({ input }),\n    });\n\n    if (!response.ok) {\n      throw new Error(`TheoKitClient: send failed with status ${response.status}`);\n    }\n\n    return (await response.json()) as SendResponse;\n  }\n\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: SSE stream parsing with fetch + ReadableStream reader requires sequential control flow\n  async *stream(input: string): AsyncGenerator<StreamEvent, void, void> {\n    const url = `${this._baseUrl}${this._basePath}/stream?input=${encodeURIComponent(input)}`;\n    const response = await fetch(url, {\n      headers: {\n        Accept: \"text/event-stream\",\n        ...this._headers,\n      },\n    });\n\n    if (!response.ok) {\n      throw new Error(`TheoKitClient: stream failed with status ${response.status}`);\n    }\n\n    const reader = response.body?.getReader();\n    if (!reader) {\n      throw new Error(\"TheoKitClient: response body is not readable\");\n    }\n\n    const decoder = new TextDecoder();\n    let buffer = \"\";\n\n    try {\n      // jscpd:ignore-start — SSE stream buffer pattern (different protocol from NDJSON in ollama-native)\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split(\"\\n\");\n        buffer = lines.pop() ?? \"\";\n        // jscpd:ignore-end\n\n        for (const line of lines) {\n          const trimmed = line.trim();\n          if (trimmed.startsWith(\"data: \")) {\n            const data = trimmed.slice(6);\n            if (data === \"[DONE]\") return;\n            try {\n              yield JSON.parse(data) as StreamEvent;\n            } catch {\n              // Skip malformed SSE data lines\n            }\n          }\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../../src/client/theokit-client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * TheoKitClient — browser-safe client for consuming server adapter endpoints\n * (T20.2, ADR D454).\n *\n * Zero Node dependencies. Uses native fetch + manual SSE parsing.\n * Consumes the same HTTP contract as server adapters (POST /send, GET /stream).\n *\n * @public\n * @deprecated since 2.x — consumes a legacy server-adapter HTTP contract\n * (`POST /agent/send`, `GET /agent/stream`) that the ecosystem no longer\n * produces. For in-process agent runs use the `Agent` façade (`@theokit/sdk`);\n * for HTTP, the framework (`theokit`) exposes agents at `POST /api/agents/<name>`\n * over a `UIMessageStream` with its own typed client. The `@theokit/sdk/client`\n * sub-path will be removed in the next major.\n */\n\nimport type { ClientOptions, SendResponse, StreamEvent } from \"./types.js\";\n\nexport class TheoKitClient {\n  private readonly _baseUrl: string;\n  private readonly _basePath: string;\n  private readonly _headers: Record<string, string>;\n\n  constructor(opts: ClientOptions) {\n    this._baseUrl = opts.baseUrl.replace(/\\/$/, \"\");\n    this._basePath = opts.basePath ?? \"/agent\";\n    this._headers = opts.headers ?? {};\n  }\n\n  async send(input: string): Promise<SendResponse> {\n    const url = `${this._baseUrl}${this._basePath}/send`;\n    const response = await fetch(url, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...this._headers,\n      },\n      body: JSON.stringify({ input }),\n    });\n\n    if (!response.ok) {\n      throw new Error(`TheoKitClient: send failed with status ${response.status}`);\n    }\n\n    return (await response.json()) as SendResponse;\n  }\n\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: SSE stream parsing with fetch + ReadableStream reader requires sequential control flow\n  async *stream(input: string): AsyncGenerator<StreamEvent, void, void> {\n    const url = `${this._baseUrl}${this._basePath}/stream?input=${encodeURIComponent(input)}`;\n    const response = await fetch(url, {\n      headers: {\n        Accept: \"text/event-stream\",\n        ...this._headers,\n      },\n    });\n\n    if (!response.ok) {\n      throw new Error(`TheoKitClient: stream failed with status ${response.status}`);\n    }\n\n    const reader = response.body?.getReader();\n    if (!reader) {\n      throw new Error(\"TheoKitClient: response body is not readable\");\n    }\n\n    const decoder = new TextDecoder();\n    let buffer = \"\";\n\n    try {\n      // jscpd:ignore-start — SSE stream buffer pattern (different protocol from NDJSON in ollama-native)\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split(\"\\n\");\n        buffer = lines.pop() ?? \"\";\n        // jscpd:ignore-end\n\n        for (const line of lines) {\n          const trimmed = line.trim();\n          if (trimmed.startsWith(\"data: \")) {\n            const data = trimmed.slice(6);\n            if (data === \"[DONE]\") return;\n            try {\n              yield JSON.parse(data) as StreamEvent;\n            } catch {\n              // Skip malformed SSE data lines\n            }\n          }\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n"]}

package/dist/client/index.d.cts

@@ -2,6 +2,11 @@
  * Client sub-path barrel (T20.2, ADR D454).
  * Exported via `@theokit/sdk/client`.
  * @public
+ * @deprecated since 2.x — the `@theokit/sdk/client` sub-path consumes a legacy
+ * server-adapter HTTP contract (`/agent/send`, `/agent/stream`) that the
+ * ecosystem no longer produces. Use the `Agent` façade (`@theokit/sdk`) for
+ * in-process runs, or the framework's `POST /api/agents/<name>` typed client for
+ * HTTP. This sub-path will be removed in the next major.
  */
 export { TheoKitClient } from "./theokit-client.js";
 export type { ClientOptions, SendResponse, StreamEvent } from "./types.js";

package/dist/client/index.d.ts

@@ -2,6 +2,11 @@
  * Client sub-path barrel (T20.2, ADR D454).
  * Exported via `@theokit/sdk/client`.
  * @public
+ * @deprecated since 2.x — the `@theokit/sdk/client` sub-path consumes a legacy
+ * server-adapter HTTP contract (`/agent/send`, `/agent/stream`) that the
+ * ecosystem no longer produces. Use the `Agent` façade (`@theokit/sdk`) for
+ * in-process runs, or the framework's `POST /api/agents/<name>` typed client for
+ * HTTP. This sub-path will be removed in the next major.
  */
 export { TheoKitClient } from "./theokit-client.js";
 export type { ClientOptions, SendResponse, StreamEvent } from "./types.js";

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/client/theokit-client.ts"],"names":[],"mappings":";AAYO,IAAM,gBAAN,MAAoB;AAAA,EACR,QAAA;AAAA,EACA,SAAA;AAAA,EACA,QAAA;AAAA,EAEjB,YAAY,IAAA,EAAqB;AAC/B,IAAA,IAAA,CAAK,QAAA,GAAW,IAAA,CAAK,OAAA,CAAQ,OAAA,CAAQ,OAAO,EAAE,CAAA;AAC9C,IAAA,IAAA,CAAK,SAAA,GAAY,KAAK,QAAA,IAAY,QAAA;AAClC,IAAA,IAAA,CAAK,QAAA,GAAW,IAAA,CAAK,OAAA,IAAW,EAAC;AAAA,EACnC;AAAA,EAEA,MAAM,KAAK,KAAA,EAAsC;AAC/C,IAAA,MAAM,MAAM,CAAA,EAAG,IAAA,CAAK,QAAQ,CAAA,EAAG,KAAK,SAAS,CAAA,KAAA,CAAA;AAC7C,IAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,GAAA,EAAK;AAAA,MAChC,MAAA,EAAQ,MAAA;AAAA,MACR,OAAA,EAAS;AAAA,QACP,cAAA,EAAgB,kBAAA;AAAA,QAChB,GAAG,IAAA,CAAK;AAAA,OACV;AAAA,MACA,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,EAAE,OAAO;AAAA,KAC/B,CAAA;AAED,IAAA,IAAI,CAAC,SAAS,EAAA,EAAI;AAChB,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,uCAAA,EAA0C,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AAAA,IAC7E;AAEA,IAAA,OAAQ,MAAM,SAAS,IAAA,EAAK;AAAA,EAC9B;AAAA;AAAA,EAGA,OAAO,OAAO,KAAA,EAAwD;AACpE,IAAA,MAAM,GAAA,GAAM,CAAA,EAAG,IAAA,CAAK,QAAQ,CAAA,EAAG,KAAK,SAAS,CAAA,cAAA,EAAiB,kBAAA,CAAmB,KAAK,CAAC,CAAA,CAAA;AACvF,IAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,GAAA,EAAK;AAAA,MAChC,OAAA,EAAS;AAAA,QACP,MAAA,EAAQ,mBAAA;AAAA,QACR,GAAG,IAAA,CAAK;AAAA;AACV,KACD,CAAA;AAED,IAAA,IAAI,CAAC,SAAS,EAAA,EAAI;AAChB,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,yCAAA,EAA4C,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AAAA,IAC/E;AAEA,IAAA,MAAM,MAAA,GAAS,QAAA,CAAS,IAAA,EAAM,SAAA,EAAU;AACxC,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,MAAM,IAAI,MAAM,8CAA8C,CAAA;AAAA,IAChE;AAEA,IAAA,MAAM,OAAA,GAAU,IAAI,WAAA,EAAY;AAChC,IAAA,IAAI,MAAA,GAAS,EAAA;AAEb,IAAA,IAAI;AAEF,MAAA,OAAO,IAAA,EAAM;AACX,QAAA,MAAM,EAAE,IAAA,EAAM,KAAA,EAAM,GAAI,MAAM,OAAO,IAAA,EAAK;AAC1C,QAAA,IAAI,IAAA,EAAM;AAEV,QAAA,MAAA,IAAU,QAAQ,MAAA,CAAO,KAAA,EAAO,EAAE,MAAA,EAAQ,MAAM,CAAA;AAChD,QAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,IAAI,CAAA;AAC/B,QAAA,MAAA,GAAS,KAAA,CAAM,KAAI,IAAK,EAAA;AAGxB,QAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,UAAA,MAAM,OAAA,GAAU,KAAK,IAAA,EAAK;AAC1B,UAAA,IAAI,OAAA,CAAQ,UAAA,CAAW,QAAQ,CAAA,EAAG;AAChC,YAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,KAAA,CAAM,CAAC,CAAA;AAC5B,YAAA,IAAI,SAAS,QAAA,EAAU;AACvB,YAAA,IAAI;AACF,cAAA,MAAM,IAAA,CAAK,MAAM,IAAI,CAAA;AAAA,YACvB,CAAA,CAAA,MAAQ;AAAA,YAER;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF,CAAA,SAAE;AACA,MAAA,MAAA,CAAO,WAAA,EAAY;AAAA,IACrB;AAAA,EACF;AACF","file":"index.js","sourcesContent":["/**\n * TheoKitClient — browser-safe client for consuming server adapter endpoints\n * (T20.2, ADR D454).\n *\n * Zero Node dependencies. Uses native fetch + manual SSE parsing.\n * Consumes the same HTTP contract as server adapters (POST /send, GET /stream).\n *\n * @public\n */\n\nimport type { ClientOptions, SendResponse, StreamEvent } from \"./types.js\";\n\nexport class TheoKitClient {\n  private readonly _baseUrl: string;\n  private readonly _basePath: string;\n  private readonly _headers: Record<string, string>;\n\n  constructor(opts: ClientOptions) {\n    this._baseUrl = opts.baseUrl.replace(/\\/$/, \"\");\n    this._basePath = opts.basePath ?? \"/agent\";\n    this._headers = opts.headers ?? {};\n  }\n\n  async send(input: string): Promise<SendResponse> {\n    const url = `${this._baseUrl}${this._basePath}/send`;\n    const response = await fetch(url, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...this._headers,\n      },\n      body: JSON.stringify({ input }),\n    });\n\n    if (!response.ok) {\n      throw new Error(`TheoKitClient: send failed with status ${response.status}`);\n    }\n\n    return (await response.json()) as SendResponse;\n  }\n\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: SSE stream parsing with fetch + ReadableStream reader requires sequential control flow\n  async *stream(input: string): AsyncGenerator<StreamEvent, void, void> {\n    const url = `${this._baseUrl}${this._basePath}/stream?input=${encodeURIComponent(input)}`;\n    const response = await fetch(url, {\n      headers: {\n        Accept: \"text/event-stream\",\n        ...this._headers,\n      },\n    });\n\n    if (!response.ok) {\n      throw new Error(`TheoKitClient: stream failed with status ${response.status}`);\n    }\n\n    const reader = response.body?.getReader();\n    if (!reader) {\n      throw new Error(\"TheoKitClient: response body is not readable\");\n    }\n\n    const decoder = new TextDecoder();\n    let buffer = \"\";\n\n    try {\n      // jscpd:ignore-start — SSE stream buffer pattern (different protocol from NDJSON in ollama-native)\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split(\"\\n\");\n        buffer = lines.pop() ?? \"\";\n        // jscpd:ignore-end\n\n        for (const line of lines) {\n          const trimmed = line.trim();\n          if (trimmed.startsWith(\"data: \")) {\n            const data = trimmed.slice(6);\n            if (data === \"[DONE]\") return;\n            try {\n              yield JSON.parse(data) as StreamEvent;\n            } catch {\n              // Skip malformed SSE data lines\n            }\n          }\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../../src/client/theokit-client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * TheoKitClient — browser-safe client for consuming server adapter endpoints\n * (T20.2, ADR D454).\n *\n * Zero Node dependencies. Uses native fetch + manual SSE parsing.\n * Consumes the same HTTP contract as server adapters (POST /send, GET /stream).\n *\n * @public\n * @deprecated since 2.x — consumes a legacy server-adapter HTTP contract\n * (`POST /agent/send`, `GET /agent/stream`) that the ecosystem no longer\n * produces. For in-process agent runs use the `Agent` façade (`@theokit/sdk`);\n * for HTTP, the framework (`theokit`) exposes agents at `POST /api/agents/<name>`\n * over a `UIMessageStream` with its own typed client. The `@theokit/sdk/client`\n * sub-path will be removed in the next major.\n */\n\nimport type { ClientOptions, SendResponse, StreamEvent } from \"./types.js\";\n\nexport class TheoKitClient {\n  private readonly _baseUrl: string;\n  private readonly _basePath: string;\n  private readonly _headers: Record<string, string>;\n\n  constructor(opts: ClientOptions) {\n    this._baseUrl = opts.baseUrl.replace(/\\/$/, \"\");\n    this._basePath = opts.basePath ?? \"/agent\";\n    this._headers = opts.headers ?? {};\n  }\n\n  async send(input: string): Promise<SendResponse> {\n    const url = `${this._baseUrl}${this._basePath}/send`;\n    const response = await fetch(url, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...this._headers,\n      },\n      body: JSON.stringify({ input }),\n    });\n\n    if (!response.ok) {\n      throw new Error(`TheoKitClient: send failed with status ${response.status}`);\n    }\n\n    return (await response.json()) as SendResponse;\n  }\n\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: SSE stream parsing with fetch + ReadableStream reader requires sequential control flow\n  async *stream(input: string): AsyncGenerator<StreamEvent, void, void> {\n    const url = `${this._baseUrl}${this._basePath}/stream?input=${encodeURIComponent(input)}`;\n    const response = await fetch(url, {\n      headers: {\n        Accept: \"text/event-stream\",\n        ...this._headers,\n      },\n    });\n\n    if (!response.ok) {\n      throw new Error(`TheoKitClient: stream failed with status ${response.status}`);\n    }\n\n    const reader = response.body?.getReader();\n    if (!reader) {\n      throw new Error(\"TheoKitClient: response body is not readable\");\n    }\n\n    const decoder = new TextDecoder();\n    let buffer = \"\";\n\n    try {\n      // jscpd:ignore-start — SSE stream buffer pattern (different protocol from NDJSON in ollama-native)\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split(\"\\n\");\n        buffer = lines.pop() ?? \"\";\n        // jscpd:ignore-end\n\n        for (const line of lines) {\n          const trimmed = line.trim();\n          if (trimmed.startsWith(\"data: \")) {\n            const data = trimmed.slice(6);\n            if (data === \"[DONE]\") return;\n            try {\n              yield JSON.parse(data) as StreamEvent;\n            } catch {\n              // Skip malformed SSE data lines\n            }\n          }\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n"]}

package/dist/client/theokit-client.d.cts

@@ -6,6 +6,12 @@
  * Consumes the same HTTP contract as server adapters (POST /send, GET /stream).
  *
  * @public
+ * @deprecated since 2.x — consumes a legacy server-adapter HTTP contract
+ * (`POST /agent/send`, `GET /agent/stream`) that the ecosystem no longer
+ * produces. For in-process agent runs use the `Agent` façade (`@theokit/sdk`);
+ * for HTTP, the framework (`theokit`) exposes agents at `POST /api/agents/<name>`
+ * over a `UIMessageStream` with its own typed client. The `@theokit/sdk/client`
+ * sub-path will be removed in the next major.
  */
 import type { ClientOptions, SendResponse, StreamEvent } from "./types.js";
 export declare class TheoKitClient {

package/dist/client/theokit-client.d.ts

@@ -6,6 +6,12 @@
  * Consumes the same HTTP contract as server adapters (POST /send, GET /stream).
  *
  * @public
+ * @deprecated since 2.x — consumes a legacy server-adapter HTTP contract
+ * (`POST /agent/send`, `GET /agent/stream`) that the ecosystem no longer
+ * produces. For in-process agent runs use the `Agent` façade (`@theokit/sdk`);
+ * for HTTP, the framework (`theokit`) exposes agents at `POST /api/agents/<name>`
+ * over a `UIMessageStream` with its own typed client. The `@theokit/sdk/client`
+ * sub-path will be removed in the next major.
  */
 import type { ClientOptions, SendResponse, StreamEvent } from "./types.js";
 export declare class TheoKitClient {

package/dist/client/types.d.cts

@@ -1,6 +1,8 @@
 /**
  * Client SDK types (T20.2, ADR D454).
  * @public
+ * @deprecated since 2.x — types for the deprecated `@theokit/sdk/client`
+ * (`TheoKitClient`) sub-path; removed with it in the next major.
  */
 export interface ClientOptions {
     baseUrl: string;

package/dist/client/types.d.ts

@@ -1,6 +1,8 @@
 /**
  * Client SDK types (T20.2, ADR D454).
  * @public
+ * @deprecated since 2.x — types for the deprecated `@theokit/sdk/client`
+ * (`TheoKitClient`) sub-path; removed with it in the next major.
  */
 export interface ClientOptions {
     baseUrl: string;

package/dist/{cron-B8fqui49.d.cts → cron-7CruUd_0.d.ts}

@@ -1,4 +1,5 @@
-import { C as CustomTool, M as ModelSelection, G as SDKUserMessage, J as SendOptions, b as Run, r as RunToCompletionOptions, s as RunToCompletionResult, S as SDKMessage, U as StreamToCompletionResult, a as McpServerConfig } from './run-BgfBWX-z.cjs';
+import { C as CustomTool, M as ModelSelection, Z as SDKUserMessage, $ as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, F as RunToCompletionOptions, H as RunToCompletionResult, S as SDKMessage, a6 as StreamToCompletionResult, a as McpServerConfig } from './run-CrIulPF7.js';
+import * as zod from 'zod';
 
 /**
  * Fork primitive public type contracts (T1.2, ADRs D110-D114).
@@ -602,6 +603,31 @@ interface StoredMessage {
     /** Optional epoch-ms timestamp. Implementations MAY default to `Date.now()` on append. */
     at?: number;
 }
+/**
+ * SE4 — light, session-level metadata stored ALONGSIDE the transcript (title +
+ * tag). Distinct from {@link StoredMessage} (which is per-turn content): this is
+ * per-conversation display metadata a host sets to build a session UI.
+ *
+ * @public
+ */
+interface SessionMeta {
+    /** Human-facing title set via `renameSession`. Absent = untitled. */
+    readonly title?: string;
+    /** Single free-form tag set via `tagSession`. Absent = untagged. */
+    readonly tag?: string;
+}
+/**
+ * SE4 — a partial update to {@link SessionMeta}. An omitted field is left
+ * unchanged; `tag: null` explicitly CLEARS the tag (distinct from omitting it).
+ *
+ * @public
+ */
+interface SessionMetaPatch {
+    /** Set the title; `null` explicitly CLEARS it (distinct from omitting it). */
+    readonly title?: string | null;
+    /** Set the tag; `null` explicitly CLEARS it (distinct from omitting it). */
+    readonly tag?: string | null;
+}
 /**
  * Pluggable conversation persistence contract.
  *
@@ -673,6 +699,19 @@ interface ConversationStorageAdapter {
      * trims old turns past a soft cap; other backends typically no-op.
      */
     compact?(conversationId: string, maxTurns: number): Promise<void>;
+    /**
+     * SE4 — optional: read the session-level metadata (title/tag) for a
+     * conversation. MUST return `undefined` when none was set (NOT throw).
+     * Adapters that cannot store side metadata MAY omit this — the session
+     * manager then reports rename/tag as unsupported rather than throwing.
+     */
+    getSessionMeta?(conversationId: string): Promise<SessionMeta | undefined>;
+    /**
+     * SE4 — optional: apply a {@link SessionMetaPatch} to a conversation's
+     * session metadata (set title, set/clear tag). MUST create the metadata
+     * lazily. Adapters that cannot store side metadata MAY omit this.
+     */
+    setSessionMeta?(conversationId: string, patch: SessionMetaPatch): Promise<void>;
     /**
      * Optional: dispose underlying handles (close DB pool, etc.).
      * MUST be safe to call multiple times.
@@ -1335,7 +1374,12 @@ interface TelemetrySettings {
  * @public
  */
 interface AgentOptions {
-    model?: ModelSelection;
+    /**
+     * The model to run. SE8 — accepts a bare-string id shorthand
+     * (`"openai/gpt-4o-mini"`, normalized to `{ id }`) OR a {@link ModelSelection}
+     * object (use the object form to pass `params`).
+     */
+    model?: string | ModelSelection;
     /** Falls back to `THEOKIT_API_KEY`. */
     apiKey?: string;
     name?: string;
@@ -1627,6 +1671,12 @@ interface SDKAgent {
      */
     readonly plugins?: SDKAgentPlugins;
     send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run>;
+    /**
+     * SE9 — integrated structured output. Runs the normal tool loop (the tools run
+     * first) then coerces the final answer into the `output` Zod schema, returning a
+     * validated, inferred-typed object. Sugar over `Agent.generateObject` (ADR D33).
+     */
+    generate<T extends zod.ZodType>(message: string | SDKUserMessage, options: GenerateOptions<T>): Promise<GenerateRunResult<zod.z.infer<T>>>;
     /** Fire-and-forget disposal. */
     close(): void;
     /** Re-read filesystem config (context, hooks, project MCP, subagents) without disposing. */
@@ -2096,4 +2146,4 @@ declare class Cron {
     static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { type GoalOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CloudRepo as D, type ContextBudget as E, type ContextManagerKind as F, type GetAgentOptions as G, type ContextSnapshot as H, type ContextSource as I, type ContextSourceStatus as J, type CreateSkillSpec as K, type LocalOptions as L, type MemorySettings as M, Cron as N, type CronCreateOptions as O, type ProviderRoutingSettings as P, type CronGetOptions as Q, type CronJob as R, type SystemPromptResolver as S, type CronJobStatus as T, type CronListOptions as U, type CronOperationOptions as V, type CronRunOptions as W, type CronRuntime as X, type CronSchedulerStatus as Y, type CronStartOptions as Z, type GoalEvent as _, type AgentDefinition as a, type GoalResult as a0, type HookName as a1, type InlineSkill as a2, type InvalidateCacheOptions as a3, type MemoryAdapter as a4, type MemoryAdapterCapabilities as a5, type MemoryContext as a6, type MemoryFact as a7, type MemoryProviderHandle as a8, type MemoryProviderInitOptions as a9, definePlugin as aA, type MemoryRevision as aa, type MemoryToolSchema as ab, type MemoryTurnMessage as ac, type PersonalityPreset as ad, type PluginContext as ae, type PostAssistantReplyContext as af, type PreToolCallContext as ag, type PreUserSendContext as ah, type PreUserSendResult as ai, type ProviderCapability as aj, type ProviderRoute as ak, type RecordSessionSummaryArgs as al, type ResolvedProviderRoute as am, type RunUntilIterator as an, type SDKAgentPlugins as ao, type SDKAgentSkills as ap, type SDKArtifact as aq, type SDKContextManager as ar, type SDKPluginMetadata as as, type SDKProvidersManager as at, type SettingSource as au, type SystemPromptContext as av, type SystemPromptMemoryFact as aw, type SystemPromptSkillRef as ax, type TelemetrySettings as ay, createSkill as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type MemoryProvider as p, type MemoryId as q, type PreToolCallDecision as r, type SDKProvider as s, type ActiveMemoryPassArgs as t, type ActiveMemoryPassResult as u, type AgentMemory as v, type BudgetCheck as w, type BudgetTotal as x, type BudgetUsageEvent as y, type CloudEnv as z };
+export { type CronStartOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetUsageEvent as D, type CloudEnv as E, type CloudRepo as F, type GetAgentOptions as G, type ContextBudget as H, type ContextManagerKind as I, type ContextSnapshot as J, type ContextSource as K, type LocalOptions as L, type MemorySettings as M, type ContextSourceStatus as N, type CreateSkillSpec as O, type ProviderRoutingSettings as P, Cron as Q, type CronCreateOptions as R, type SystemPromptResolver as S, type CronGetOptions as T, type CronJob as U, type CronJobStatus as V, type CronListOptions as W, type CronOperationOptions as X, type CronRunOptions as Y, type CronRuntime as Z, type CronSchedulerStatus as _, type AgentDefinition as a, type GoalEvent as a0, type GoalOptions as a1, type GoalResult as a2, type HookName as a3, type InlineSkill as a4, type InvalidateCacheOptions as a5, type MemoryAdapter as a6, type MemoryAdapterCapabilities as a7, type MemoryContext as a8, type MemoryFact as a9, type TelemetrySettings as aA, createSkill as aB, definePlugin as aC, type MemoryProviderHandle as aa, type MemoryProviderInitOptions as ab, type MemoryRevision as ac, type MemoryToolSchema as ad, type MemoryTurnMessage as ae, type PersonalityPreset as af, type PluginContext as ag, type PostAssistantReplyContext as ah, type PreToolCallContext as ai, type PreUserSendContext as aj, type PreUserSendResult as ak, type ProviderCapability as al, type ProviderRoute as am, type RecordSessionSummaryArgs as an, type ResolvedProviderRoute as ao, type RunUntilIterator as ap, type SDKAgentPlugins as aq, type SDKAgentSkills as ar, type SDKArtifact as as, type SDKContextManager as at, type SDKPluginMetadata as au, type SDKProvidersManager as av, type SettingSource as aw, type SystemPromptContext as ax, type SystemPromptMemoryFact as ay, type SystemPromptSkillRef as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type SessionMeta as p, type SessionMetaPatch as q, type MemoryProvider as r, type MemoryId as s, type PreToolCallDecision as t, type SDKProvider as u, type ActiveMemoryPassArgs as v, type ActiveMemoryPassResult as w, type AgentMemory as x, type BudgetCheck as y, type BudgetTotal as z };

package/dist/{cron-D2yLOrk2.d.ts → cron-Bpt_1khA.d.cts}

@@ -1,4 +1,5 @@
-import { C as CustomTool, M as ModelSelection, G as SDKUserMessage, J as SendOptions, b as Run, r as RunToCompletionOptions, s as RunToCompletionResult, S as SDKMessage, U as StreamToCompletionResult, a as McpServerConfig } from './run-BgfBWX-z.js';
+import { C as CustomTool, M as ModelSelection, Z as SDKUserMessage, $ as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, F as RunToCompletionOptions, H as RunToCompletionResult, S as SDKMessage, a6 as StreamToCompletionResult, a as McpServerConfig } from './run-CrIulPF7.cjs';
+import * as zod from 'zod';
 
 /**
  * Fork primitive public type contracts (T1.2, ADRs D110-D114).
@@ -602,6 +603,31 @@ interface StoredMessage {
     /** Optional epoch-ms timestamp. Implementations MAY default to `Date.now()` on append. */
     at?: number;
 }
+/**
+ * SE4 — light, session-level metadata stored ALONGSIDE the transcript (title +
+ * tag). Distinct from {@link StoredMessage} (which is per-turn content): this is
+ * per-conversation display metadata a host sets to build a session UI.
+ *
+ * @public
+ */
+interface SessionMeta {
+    /** Human-facing title set via `renameSession`. Absent = untitled. */
+    readonly title?: string;
+    /** Single free-form tag set via `tagSession`. Absent = untagged. */
+    readonly tag?: string;
+}
+/**
+ * SE4 — a partial update to {@link SessionMeta}. An omitted field is left
+ * unchanged; `tag: null` explicitly CLEARS the tag (distinct from omitting it).
+ *
+ * @public
+ */
+interface SessionMetaPatch {
+    /** Set the title; `null` explicitly CLEARS it (distinct from omitting it). */
+    readonly title?: string | null;
+    /** Set the tag; `null` explicitly CLEARS it (distinct from omitting it). */
+    readonly tag?: string | null;
+}
 /**
  * Pluggable conversation persistence contract.
  *
@@ -673,6 +699,19 @@ interface ConversationStorageAdapter {
      * trims old turns past a soft cap; other backends typically no-op.
      */
     compact?(conversationId: string, maxTurns: number): Promise<void>;
+    /**
+     * SE4 — optional: read the session-level metadata (title/tag) for a
+     * conversation. MUST return `undefined` when none was set (NOT throw).
+     * Adapters that cannot store side metadata MAY omit this — the session
+     * manager then reports rename/tag as unsupported rather than throwing.
+     */
+    getSessionMeta?(conversationId: string): Promise<SessionMeta | undefined>;
+    /**
+     * SE4 — optional: apply a {@link SessionMetaPatch} to a conversation's
+     * session metadata (set title, set/clear tag). MUST create the metadata
+     * lazily. Adapters that cannot store side metadata MAY omit this.
+     */
+    setSessionMeta?(conversationId: string, patch: SessionMetaPatch): Promise<void>;
     /**
      * Optional: dispose underlying handles (close DB pool, etc.).
      * MUST be safe to call multiple times.
@@ -1335,7 +1374,12 @@ interface TelemetrySettings {
  * @public
  */
 interface AgentOptions {
-    model?: ModelSelection;
+    /**
+     * The model to run. SE8 — accepts a bare-string id shorthand
+     * (`"openai/gpt-4o-mini"`, normalized to `{ id }`) OR a {@link ModelSelection}
+     * object (use the object form to pass `params`).
+     */
+    model?: string | ModelSelection;
     /** Falls back to `THEOKIT_API_KEY`. */
     apiKey?: string;
     name?: string;
@@ -1627,6 +1671,12 @@ interface SDKAgent {
      */
     readonly plugins?: SDKAgentPlugins;
     send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run>;
+    /**
+     * SE9 — integrated structured output. Runs the normal tool loop (the tools run
+     * first) then coerces the final answer into the `output` Zod schema, returning a
+     * validated, inferred-typed object. Sugar over `Agent.generateObject` (ADR D33).
+     */
+    generate<T extends zod.ZodType>(message: string | SDKUserMessage, options: GenerateOptions<T>): Promise<GenerateRunResult<zod.z.infer<T>>>;
     /** Fire-and-forget disposal. */
     close(): void;
     /** Re-read filesystem config (context, hooks, project MCP, subagents) without disposing. */
@@ -2096,4 +2146,4 @@ declare class Cron {
     static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { type GoalOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CloudRepo as D, type ContextBudget as E, type ContextManagerKind as F, type GetAgentOptions as G, type ContextSnapshot as H, type ContextSource as I, type ContextSourceStatus as J, type CreateSkillSpec as K, type LocalOptions as L, type MemorySettings as M, Cron as N, type CronCreateOptions as O, type ProviderRoutingSettings as P, type CronGetOptions as Q, type CronJob as R, type SystemPromptResolver as S, type CronJobStatus as T, type CronListOptions as U, type CronOperationOptions as V, type CronRunOptions as W, type CronRuntime as X, type CronSchedulerStatus as Y, type CronStartOptions as Z, type GoalEvent as _, type AgentDefinition as a, type GoalResult as a0, type HookName as a1, type InlineSkill as a2, type InvalidateCacheOptions as a3, type MemoryAdapter as a4, type MemoryAdapterCapabilities as a5, type MemoryContext as a6, type MemoryFact as a7, type MemoryProviderHandle as a8, type MemoryProviderInitOptions as a9, definePlugin as aA, type MemoryRevision as aa, type MemoryToolSchema as ab, type MemoryTurnMessage as ac, type PersonalityPreset as ad, type PluginContext as ae, type PostAssistantReplyContext as af, type PreToolCallContext as ag, type PreUserSendContext as ah, type PreUserSendResult as ai, type ProviderCapability as aj, type ProviderRoute as ak, type RecordSessionSummaryArgs as al, type ResolvedProviderRoute as am, type RunUntilIterator as an, type SDKAgentPlugins as ao, type SDKAgentSkills as ap, type SDKArtifact as aq, type SDKContextManager as ar, type SDKPluginMetadata as as, type SDKProvidersManager as at, type SettingSource as au, type SystemPromptContext as av, type SystemPromptMemoryFact as aw, type SystemPromptSkillRef as ax, type TelemetrySettings as ay, createSkill as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type MemoryProvider as p, type MemoryId as q, type PreToolCallDecision as r, type SDKProvider as s, type ActiveMemoryPassArgs as t, type ActiveMemoryPassResult as u, type AgentMemory as v, type BudgetCheck as w, type BudgetTotal as x, type BudgetUsageEvent as y, type CloudEnv as z };
+export { type CronStartOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetUsageEvent as D, type CloudEnv as E, type CloudRepo as F, type GetAgentOptions as G, type ContextBudget as H, type ContextManagerKind as I, type ContextSnapshot as J, type ContextSource as K, type LocalOptions as L, type MemorySettings as M, type ContextSourceStatus as N, type CreateSkillSpec as O, type ProviderRoutingSettings as P, Cron as Q, type CronCreateOptions as R, type SystemPromptResolver as S, type CronGetOptions as T, type CronJob as U, type CronJobStatus as V, type CronListOptions as W, type CronOperationOptions as X, type CronRunOptions as Y, type CronRuntime as Z, type CronSchedulerStatus as _, type AgentDefinition as a, type GoalEvent as a0, type GoalOptions as a1, type GoalResult as a2, type HookName as a3, type InlineSkill as a4, type InvalidateCacheOptions as a5, type MemoryAdapter as a6, type MemoryAdapterCapabilities as a7, type MemoryContext as a8, type MemoryFact as a9, type TelemetrySettings as aA, createSkill as aB, definePlugin as aC, type MemoryProviderHandle as aa, type MemoryProviderInitOptions as ab, type MemoryRevision as ac, type MemoryToolSchema as ad, type MemoryTurnMessage as ae, type PersonalityPreset as af, type PluginContext as ag, type PostAssistantReplyContext as ah, type PreToolCallContext as ai, type PreUserSendContext as aj, type PreUserSendResult as ak, type ProviderCapability as al, type ProviderRoute as am, type RecordSessionSummaryArgs as an, type ResolvedProviderRoute as ao, type RunUntilIterator as ap, type SDKAgentPlugins as aq, type SDKAgentSkills as ar, type SDKArtifact as as, type SDKContextManager as at, type SDKPluginMetadata as au, type SDKProvidersManager as av, type SettingSource as aw, type SystemPromptContext as ax, type SystemPromptMemoryFact as ay, type SystemPromptSkillRef as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type SessionMeta as p, type SessionMetaPatch as q, type MemoryProvider as r, type MemoryId as s, type PreToolCallDecision as t, type SDKProvider as u, type ActiveMemoryPassArgs as v, type ActiveMemoryPassResult as w, type AgentMemory as x, type BudgetCheck as y, type BudgetTotal as z };