@theokit/sdk 2.28.0 → 2.29.0

package/dist/internal/persistence/conversation-storage-fs.d.cts

@@ -17,6 +17,7 @@
  * @public
  */
 import type { ConversationStorageAdapter, SessionMeta, SessionMetaPatch, StoredMessage } from "../../types/conversation-storage.js";
+import type { ObjectiveRecord } from "../../types/objective.js";
 export interface FileSystemConversationStorageOptions {
     /** Root directory under which `.theokit/agents/<id>/` lives. Defaults to `process.cwd()`. */
     root?: string;
@@ -41,5 +42,8 @@ export declare class FileSystemConversationStorage implements ConversationStorag
     compact(conversationId: string, maxTurns: number): Promise<void>;
     getSessionMeta(conversationId: string): Promise<SessionMeta | undefined>;
     setSessionMeta(conversationId: string, patch: SessionMetaPatch): Promise<void>;
+    getObjectiveRecord(conversationId: string): Promise<ObjectiveRecord | undefined>;
+    setObjectiveRecord(conversationId: string, record: ObjectiveRecord | null): Promise<void>;
+    updateObjectiveRecord(conversationId: string, mutate: (current: ObjectiveRecord | undefined) => ObjectiveRecord | null | undefined): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/internal/persistence/conversation-storage-fs.d.ts

@@ -17,6 +17,7 @@
  * @public
  */
 import type { ConversationStorageAdapter, SessionMeta, SessionMetaPatch, StoredMessage } from "../../types/conversation-storage.js";
+import type { ObjectiveRecord } from "../../types/objective.js";
 export interface FileSystemConversationStorageOptions {
     /** Root directory under which `.theokit/agents/<id>/` lives. Defaults to `process.cwd()`. */
     root?: string;
@@ -41,5 +42,8 @@ export declare class FileSystemConversationStorage implements ConversationStorag
     compact(conversationId: string, maxTurns: number): Promise<void>;
     getSessionMeta(conversationId: string): Promise<SessionMeta | undefined>;
     setSessionMeta(conversationId: string, patch: SessionMetaPatch): Promise<void>;
+    getObjectiveRecord(conversationId: string): Promise<ObjectiveRecord | undefined>;
+    setObjectiveRecord(conversationId: string, record: ObjectiveRecord | null): Promise<void>;
+    updateObjectiveRecord(conversationId: string, mutate: (current: ObjectiveRecord | undefined) => ObjectiveRecord | null | undefined): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/internal/persistence/conversation-storage-memory.d.cts

@@ -12,6 +12,7 @@
  * @public
  */
 import type { ConversationStorageAdapter, SessionMeta, SessionMetaPatch, StoredMessage } from "../../types/conversation-storage.js";
+import type { ObjectiveRecord } from "../../types/objective.js";
 export declare class InMemoryConversationStorage implements ConversationStorageAdapter {
     #private;
     getMessages(conversationId: string, opts?: {
@@ -28,5 +29,8 @@ export declare class InMemoryConversationStorage implements ConversationStorageA
     }): Promise<readonly string[]>;
     getSessionMeta(conversationId: string): Promise<SessionMeta | undefined>;
     setSessionMeta(conversationId: string, patch: SessionMetaPatch): Promise<void>;
+    getObjectiveRecord(conversationId: string): Promise<ObjectiveRecord | undefined>;
+    setObjectiveRecord(conversationId: string, record: ObjectiveRecord | null): Promise<void>;
+    updateObjectiveRecord(conversationId: string, mutate: (current: ObjectiveRecord | undefined) => ObjectiveRecord | null | undefined): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/internal/persistence/conversation-storage-memory.d.ts

@@ -12,6 +12,7 @@
  * @public
  */
 import type { ConversationStorageAdapter, SessionMeta, SessionMetaPatch, StoredMessage } from "../../types/conversation-storage.js";
+import type { ObjectiveRecord } from "../../types/objective.js";
 export declare class InMemoryConversationStorage implements ConversationStorageAdapter {
     #private;
     getMessages(conversationId: string, opts?: {
@@ -28,5 +29,8 @@ export declare class InMemoryConversationStorage implements ConversationStorageA
     }): Promise<readonly string[]>;
     getSessionMeta(conversationId: string): Promise<SessionMeta | undefined>;
     setSessionMeta(conversationId: string, patch: SessionMetaPatch): Promise<void>;
+    getObjectiveRecord(conversationId: string): Promise<ObjectiveRecord | undefined>;
+    setObjectiveRecord(conversationId: string, record: ObjectiveRecord | null): Promise<void>;
+    updateObjectiveRecord(conversationId: string, mutate: (current: ObjectiveRecord | undefined) => ObjectiveRecord | null | undefined): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/internal/persistence/objective-coerce.d.cts

@@ -0,0 +1,9 @@
+/**
+ * SE33 (ADR 0012) — coerce an untrusted parsed JSON value into an
+ * {@link ObjectiveRecord}, or `undefined` when the shape is not a valid record.
+ * Malformed JSON is caught upstream (the reader distinguishes ENOENT); this
+ * guards against a structurally-wrong but valid-JSON file.
+ *
+ * @internal
+ */
+export declare function coerceObjectiveRecord(raw: unknown): ObjectiveRecord | undefined;

package/dist/internal/persistence/objective-coerce.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SE33 (ADR 0012) — coerce an untrusted parsed JSON value into an
+ * {@link ObjectiveRecord}, or `undefined` when the shape is not a valid record.
+ * Malformed JSON is caught upstream (the reader distinguishes ENOENT); this
+ * guards against a structurally-wrong but valid-JSON file.
+ *
+ * @internal
+ */
+export declare function coerceObjectiveRecord(raw: unknown): ObjectiveRecord | undefined;

package/dist/internal/runtime/lifecycle/wrap-completion-check-run.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SE34 — wrap a {@link Run} so a finished reply is scored by the shipped
+ * LLM-as-judge against {@link SendOptions.completionCheck} (`isTaskComplete`).
+ * The verdict is attached to `wait()`'s {@link RunResult.completionCheck} and a
+ * `completion_check` run-event is emitted. This is the finer-grained, single-
+ * `send()` completion gate (contrast `runUntil`, which judges BETWEEN sends).
+ *
+ * Non-invasive: only wraps when `completionCheck` is set, only judges a
+ * `finished` run with text, memoizes so the judge runs EXACTLY ONCE, and a
+ * Proxy preserves every other Run member. A fail-safe: a judge parse failure
+ * yields `complete: false` (never silently "done"). The judge model is injected
+ * via `deps.judge` so this module stays free of the Agent façade import.
+ *
+ * The judge fires from `wait()` (not from `stream()`); a stream-only consumer
+ * must call `wait()` to trigger the verdict + the `completion_check` event.
+ *
+ * @internal
+ */
+import { type RunEventSink } from "../../../types/run-events.js";
+import type { JudgeContext, JudgeOptions } from "../../judge/judge-call.js";
+import type { JudgeResult } from "../../judge/types.js";
+export interface CompletionCheckDeps {
+    judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;
+}
+export declare function wrapRunWithCompletionCheck(args: {
+    run: Run;
+    completionCheck: CompletionCheck | undefined;
+    onRunEvent: RunEventSink | undefined;
+    deps: CompletionCheckDeps;
+}): Run;

package/dist/internal/runtime/local-agent/local-agent-goal-extensions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SE33 (ADR 0012) — the durable-objective agent methods, extracted from
+ * `local-agent.ts` (G8 budget) mirroring `local-agent-runtime-extensions.ts`.
+ * Each resolves the agent's storage handle to a `ConversationStorageAdapter` and
+ * delegates to the pure `objective-store`. All no-op when the run is not
+ * memory-backed (an adapter that omits the optional objective methods).
+ *
+ * @internal
+ */
+import type { ConversationStorageAdapter } from "../../../types/conversation-storage.js";
+import type { GoalOptions, GoalResult } from "../../../types/goal-events.js";
+import type { AgentGoalConfig, DurableGoalOptions, ObjectiveRecord } from "../../../types/objective.js";
+export declare function localAgentSetObjective(handle: ConversationStorageAdapter | string, objective: string, opts: {
+    threadId: string;
+} & DurableGoalOptions): Promise<void>;
+export declare function localAgentGetObjective(handle: ConversationStorageAdapter | string, opts: {
+    threadId: string;
+}): Promise<ObjectiveRecord | undefined>;
+export declare function localAgentUpdateObjectiveOptions(handle: ConversationStorageAdapter | string, opts: {
+    threadId: string;
+} & DurableGoalOptions): Promise<void>;
+export declare function localAgentClearObjective(handle: ConversationStorageAdapter | string, opts: {
+    threadId: string;
+}): Promise<void>;
+/**
+ * SE34 — resolve the ACTIVE durable objective text for a thread, for the
+ * `<current-objective>` context projection. Returns `undefined` when no
+ * objective is set, the run is not memory-backed, or the objective is no longer
+ * active (`done`/`paused` ⇒ nothing to project this turn).
+ */
+export declare function resolveCurrentObjectiveText(handle: ConversationStorageAdapter | string, threadId: string): Promise<string | undefined>;
+/**
+ * SE34 — format the `<current-objective>` context signal, prepended to the
+ * assembled system prompt (or standalone when there is none). Pure — the string
+ * shape is locked here so the projection is testable without a live send.
+ */
+export declare function formatObjectiveProjection(objective: string, assembled: string | undefined): string;
+/**
+ * Outcome of resolving a `runUntil()` call with NO explicit goal against the
+ * durable thread-scoped objective (ADR D3/D4):
+ * - `run`   — an objective is set AND a judge resolves; carries the effective run.
+ * - `inert` — an objective is set but NO explicit judge resolves; the standing
+ *             objective is inert (no scoring, no budget consumed) — the judge is
+ *             the activation switch (ADR D3, mirroring Mastra).
+ * - `exhausted` — an objective is set + activated but its durable budget
+ *             (`maxRuns`) is spent; the loop is NOT entered (a 0-turn run would
+ *             burn a judge call for nothing). Raising `maxRuns` later resumes it.
+ * - `none`  — no objective set for the thread.
+ */
+export type DurableRunResolution = {
+    kind: "run";
+    goal: string;
+    options: GoalOptions;
+} | {
+    kind: "inert";
+} | {
+    kind: "exhausted";
+} | {
+    kind: "none";
+};
+/**
+ * Resolve a `runUntil()` call with NO explicit goal against the durable
+ * thread-scoped objective (ADR D4).
+ *
+ * Precedence (ADR D3): per-call option → per-objective option → standing agent
+ * `goal` config → built-in default. The per-call `maxTurns` (if any) is capped
+ * by the durable budget remaining (`maxRuns - runsUsed`), so the objective can
+ * never overrun its total run budget across resumes. Activation requires an
+ * EXPLICIT judge (per-objective `judgeModel` or standing `goal.judgeModel`); the
+ * built-in default judge does NOT auto-activate a standing objective.
+ */
+export declare function resolveDurableRun(handle: ConversationStorageAdapter | string, goalConfig: AgentGoalConfig | undefined, threadId: string, callerOptions: GoalOptions | undefined): Promise<DurableRunResolution>;
+/**
+ * Write a completed `runUntil()` pass back into the durable objective (ADR D4):
+ * accumulate `runsUsed`, and map the loop result to a durable status —
+ * `completed → done`, `paused → paused`, `failed (budget exhausted) → active`
+ * so a later `runUntil()` resumes the same objective. No-op when the objective
+ * was cleared mid-run.
+ */
+export declare function persistDurableProgress(handle: ConversationStorageAdapter | string, threadId: string, result: GoalResult): Promise<void>;

package/dist/internal/runtime/objective/objective-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SE33 (ADR 0012) — the pure durable-objective store over a
+ * `ConversationStorageAdapter`. Set / get / update-options / clear / write-back
+ * progress for a thread-scoped {@link ObjectiveRecord}. Every operation is a
+ * no-op (typed degradation, never throws) when the adapter omits the optional
+ * `getObjectiveRecord` / `setObjectiveRecord` methods — the same contract SE4's
+ * session manager uses.
+ *
+ * @internal
+ */
+import type { DurableGoalOptions, ObjectiveRecord, ObjectiveStatus } from "../../../types/objective.js";
+/** Read the durable objective for `conversationId`, or `undefined` (unset / unsupported). */
+export declare function getObjective(adapter: ConversationStorageAdapter, conversationId: string): Promise<ObjectiveRecord | undefined>;
+/** Set a FRESH objective (status `active`, `runsUsed` 0). Overwrites any prior record. */
+export declare function setObjective(adapter: ConversationStorageAdapter, conversationId: string, objective: string, options?: DurableGoalOptions): Promise<void>;
+/**
+ * Merge `patch` into the active objective's `options` (only provided fields
+ * change). No-op when no objective is set. Keeps `objective` / `status` /
+ * `runsUsed` unchanged. Atomic read-modify-write via {@link mutateObjective}.
+ */
+export declare function updateObjectiveOptions(adapter: ConversationStorageAdapter, conversationId: string, patch: DurableGoalOptions): Promise<void>;
+/**
+ * Write back loop progress (`runsUsed` + `status`) after a `runUntil` pass. No-op
+ * when unset. Atomic read-modify-write via {@link mutateObjective} — the read that
+ * feeds the increment happens under the adapter's lock, so concurrent write-backs
+ * on one thread cannot drop turns (HIGH-1).
+ */
+export declare function writeObjectiveProgress(adapter: ConversationStorageAdapter, conversationId: string, progress: {
+    runsUsed: number;
+    status: ObjectiveStatus;
+}): Promise<void>;
+/** Clear the durable objective for `conversationId`. */
+export declare function clearObjective(adapter: ConversationStorageAdapter, conversationId: string): Promise<void>;

package/dist/{run-CdWiihyU.d.cts → run-q_P0vHlY.d.cts}

@@ -87,7 +87,7 @@ interface ToolResultGuardOptions {
  *
  * @public
  */
-type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunTripwireEvent;
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunTripwireEvent | RunCompletionCheckEvent;
 /**
  * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
  * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
@@ -144,6 +144,17 @@ interface RunTaskCompletedEvent {
     readonly taskId: string;
     readonly status: "completed" | "failed" | "stopped";
 }
+/**
+ * SE34 — the per-send completion check (`isTaskComplete`) produced a verdict.
+ * Emitted once, after a finished run's reply is judged against
+ * {@link SendOptions.completionCheck}. Distinct from `task_completed` (which is
+ * background-task/subagent lifecycle). Mirrors {@link RunResult.completionCheck}.
+ */
+interface RunCompletionCheckEvent {
+    readonly type: "completion_check";
+    readonly complete: boolean;
+    readonly reason: string;
+}
 /** The conversation crossed a compaction boundary (history was summarized). */
 interface RunCompactBoundaryEvent {
     readonly type: "compact_boundary";
@@ -1052,6 +1063,13 @@ interface RunResult {
      * @public
      */
     stoppedByDoomLoop?: boolean;
+    /**
+     * SE34 — the per-send completion verdict, populated when
+     * {@link SendOptions.completionCheck} was set AND the run finished. Absent on
+     * non-finished runs and when no completion check was requested. Reuses the
+     * shipped LLM-as-judge (same one `runUntil` drives). @public
+     */
+    completionCheck?: CompletionCheckResult;
 }
 /**
  * Doom-loop guard thresholds (see {@link SendOptions.doomLoop}). Both are counts of CONSECUTIVE
@@ -1324,6 +1342,57 @@ interface SendOptions {
      * @public
      */
     maxIterations?: number;
+    /**
+     * SE34 — per-send completion check (`isTaskComplete`). After this single
+     * `send()` reaches a terminal `finished` state, the shipped LLM-as-judge
+     * scores the final reply against `criteria` and surfaces the verdict on
+     * {@link RunResult.completionCheck} + a `completion_check` run-event. This is
+     * the finer-grained, single-`send()` gate (contrast `runUntil`, which judges
+     * the FULL response BETWEEN sends). Opt-in — absent ⇒ the send is byte-identical
+     * to today (no extra judge call). Non-finished runs skip the check. The judge
+     * runs when `wait()` is called on the returned `Run`; a stream-only consumer
+     * must call `wait()` to trigger the verdict + the `completion_check` event.
+     *
+     * @public
+     */
+    completionCheck?: CompletionCheck;
+    /**
+     * SE34 — project the standing durable objective (SE33) for this `threadId`
+     * into the model context for this send as `<current-objective>…`, so the
+     * model always sees what it is working toward. Opt-in — absent ⇒ the assembled
+     * system prompt is byte-identical to today. Only an ACTIVE objective is
+     * projected (`done`/`paused` ⇒ nothing injected). Reuses the SE33 objective
+     * store + the system-prompt assembly seam (no general signal framework — YAGNI).
+     *
+     * @public
+     */
+    objectiveThreadId?: string;
+}
+/**
+ * SE34 — the per-send completion criterion (see {@link SendOptions.completionCheck}).
+ *
+ * @public
+ */
+interface CompletionCheck {
+    /** What "complete" means for this send — fed to the judge as the goal. */
+    criteria: string;
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"`. */
+    judgeModel?: string;
+    /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY`. */
+    apiKey?: string;
+}
+/**
+ * SE34 — the resolved per-send completion verdict (see {@link RunResult.completionCheck}).
+ *
+ * @public
+ */
+interface CompletionCheckResult {
+    /** `true` when the judge ruled the send's reply satisfies the criteria. */
+    complete: boolean;
+    /** The judge's stated reason. */
+    reason: string;
+    /** `true` when the judge output could not be parsed — fail-safe `complete: false`. */
+    parseFailed: boolean;
 }
 /**
  * Handle to a single prompt submission.
@@ -1397,4 +1466,4 @@ interface GenerateRunResult<O> {
     };
 }
 
-export { type SDKStatusMessage as $, type AgentConversationTurn as A, type RunOperation as B, type CustomTool as C, type DoomLoopThresholds as D, type RunPermissionDeniedEvent as E, type RunRateLimitEvent as F, type GenerateOptions as G, type RunStatus as H, type ImageBlock as I, type RunTaskCompletedEvent as J, type RunTaskStartedEvent as K, type RunTaskUpdatedEvent as L, type ModelSelection as M, type RunToCompletionOptions as N, type OutputProcessorContext as O, type Processor as P, type RunToCompletionResult as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunToolProgressEvent as U, type RunTripwireEvent as V, type SDKAssistantMessage as W, type SDKImage as X, type SDKImageDimension as Y, type SDKObjectDelta as Z, type SDKRequestMessage as _, type McpServerConfig as a, type SDKSystemMessage as a0, type SDKTaskMessage as a1, type SDKThinkingMessage as a2, type SDKToolUseMessage as a3, type SDKUserMessage as a4, type SDKUserMessageEvent as a5, type SendOptions as a6, type ShellCommand as a7, type ShellConversationTurn as a8, type ShellOutput as a9, type ShellOutputDeltaUpdate as aa, type StepCompletedUpdate as ab, type StepStartedUpdate as ac, type StreamToCompletionResult as ad, type SummaryCompletedUpdate as ae, type SummaryStartedUpdate as af, type SummaryUpdate as ag, type TextBlock as ah, type TextDeltaUpdate as ai, type ThinkingCompletedUpdate as aj, type ThinkingDeltaUpdate as ak, type ThinkingMessage as al, type TokenDeltaUpdate as am, type TokenUsage as an, type ToolCall as ao, type ToolCallCompletedUpdate as ap, type ToolCallStartedUpdate as aq, type ToolContextMessage as ar, type ToolResult as as, type ToolResultGuardOptions as at, type ToolUseBlock as au, type TurnEndedUpdate as av, type UserMessage as aw, type UserMessageAppendedUpdate as ax, emitRunEvent as ay, type Run as b, type MessageOrigin as c, type AssistantMessage as d, type ConversationStep as e, type ConversationTurn as f, type CostBreakdown as g, type CostSource as h, type CostStatus as i, type GenerateRunResult as j, type InputProcessorContext as k, type InteractionUpdate as l, type McpAuthConfig as m, type McpHttpServerConfig as n, type McpOAuthConfig as o, type McpStdioServerConfig as p, type ModelParameterValue as q, type PartialToolCallUpdate as r, type ProcessorControls as s, type ProcessorTripwire as t, type ProcessorViolation as u, type RunCompactBoundaryEvent as v, type RunErrorDetail as w, type RunEvent as x, type RunEventSink as y, type RunGitInfo as z };
+export { type SDKImageDimension as $, type AgentConversationTurn as A, type RunEvent as B, type CustomTool as C, type DoomLoopThresholds as D, type RunEventSink as E, type RunGitInfo as F, type GenerateOptions as G, type RunOperation as H, type ImageBlock as I, type RunPermissionDeniedEvent as J, type RunRateLimitEvent as K, type RunStatus as L, type ModelSelection as M, type RunTaskCompletedEvent as N, type OutputProcessorContext as O, type Processor as P, type RunTaskStartedEvent as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunTaskUpdatedEvent as U, type RunToCompletionOptions as V, type RunToCompletionResult as W, type RunToolProgressEvent as X, type RunTripwireEvent as Y, type SDKAssistantMessage as Z, type SDKImage as _, type McpServerConfig as a, type SDKObjectDelta as a0, type SDKRequestMessage as a1, type SDKStatusMessage as a2, type SDKSystemMessage as a3, type SDKTaskMessage as a4, type SDKThinkingMessage as a5, type SDKToolUseMessage as a6, type SDKUserMessage as a7, type SDKUserMessageEvent as a8, type SendOptions as a9, type UserMessageAppendedUpdate as aA, emitRunEvent as aB, type ShellCommand as aa, type ShellConversationTurn as ab, type ShellOutput as ac, type ShellOutputDeltaUpdate as ad, type StepCompletedUpdate as ae, type StepStartedUpdate as af, type StreamToCompletionResult as ag, type SummaryCompletedUpdate as ah, type SummaryStartedUpdate as ai, type SummaryUpdate as aj, type TextBlock as ak, type TextDeltaUpdate as al, type ThinkingCompletedUpdate as am, type ThinkingDeltaUpdate as an, type ThinkingMessage as ao, type TokenDeltaUpdate as ap, type TokenUsage as aq, type ToolCall as ar, type ToolCallCompletedUpdate as as, type ToolCallStartedUpdate as at, type ToolContextMessage as au, type ToolResult as av, type ToolResultGuardOptions as aw, type ToolUseBlock as ax, type TurnEndedUpdate as ay, type UserMessage as az, type Run as b, type MessageOrigin as c, type AssistantMessage as d, type CompletionCheck as e, type CompletionCheckResult as f, type ConversationStep as g, type ConversationTurn as h, type CostBreakdown as i, type CostSource as j, type CostStatus as k, type GenerateRunResult as l, type InputProcessorContext as m, type InteractionUpdate as n, type McpAuthConfig as o, type McpHttpServerConfig as p, type McpOAuthConfig as q, type McpStdioServerConfig as r, type ModelParameterValue as s, type PartialToolCallUpdate as t, type ProcessorControls as u, type ProcessorTripwire as v, type ProcessorViolation as w, type RunCompactBoundaryEvent as x, type RunCompletionCheckEvent as y, type RunErrorDetail as z };

package/dist/{run-CdWiihyU.d.ts → run-q_P0vHlY.d.ts}

@@ -87,7 +87,7 @@ interface ToolResultGuardOptions {
  *
  * @public
  */
-type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunTripwireEvent;
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunTripwireEvent | RunCompletionCheckEvent;
 /**
  * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
  * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
@@ -144,6 +144,17 @@ interface RunTaskCompletedEvent {
     readonly taskId: string;
     readonly status: "completed" | "failed" | "stopped";
 }
+/**
+ * SE34 — the per-send completion check (`isTaskComplete`) produced a verdict.
+ * Emitted once, after a finished run's reply is judged against
+ * {@link SendOptions.completionCheck}. Distinct from `task_completed` (which is
+ * background-task/subagent lifecycle). Mirrors {@link RunResult.completionCheck}.
+ */
+interface RunCompletionCheckEvent {
+    readonly type: "completion_check";
+    readonly complete: boolean;
+    readonly reason: string;
+}
 /** The conversation crossed a compaction boundary (history was summarized). */
 interface RunCompactBoundaryEvent {
     readonly type: "compact_boundary";
@@ -1052,6 +1063,13 @@ interface RunResult {
      * @public
      */
     stoppedByDoomLoop?: boolean;
+    /**
+     * SE34 — the per-send completion verdict, populated when
+     * {@link SendOptions.completionCheck} was set AND the run finished. Absent on
+     * non-finished runs and when no completion check was requested. Reuses the
+     * shipped LLM-as-judge (same one `runUntil` drives). @public
+     */
+    completionCheck?: CompletionCheckResult;
 }
 /**
  * Doom-loop guard thresholds (see {@link SendOptions.doomLoop}). Both are counts of CONSECUTIVE
@@ -1324,6 +1342,57 @@ interface SendOptions {
      * @public
      */
     maxIterations?: number;
+    /**
+     * SE34 — per-send completion check (`isTaskComplete`). After this single
+     * `send()` reaches a terminal `finished` state, the shipped LLM-as-judge
+     * scores the final reply against `criteria` and surfaces the verdict on
+     * {@link RunResult.completionCheck} + a `completion_check` run-event. This is
+     * the finer-grained, single-`send()` gate (contrast `runUntil`, which judges
+     * the FULL response BETWEEN sends). Opt-in — absent ⇒ the send is byte-identical
+     * to today (no extra judge call). Non-finished runs skip the check. The judge
+     * runs when `wait()` is called on the returned `Run`; a stream-only consumer
+     * must call `wait()` to trigger the verdict + the `completion_check` event.
+     *
+     * @public
+     */
+    completionCheck?: CompletionCheck;
+    /**
+     * SE34 — project the standing durable objective (SE33) for this `threadId`
+     * into the model context for this send as `<current-objective>…`, so the
+     * model always sees what it is working toward. Opt-in — absent ⇒ the assembled
+     * system prompt is byte-identical to today. Only an ACTIVE objective is
+     * projected (`done`/`paused` ⇒ nothing injected). Reuses the SE33 objective
+     * store + the system-prompt assembly seam (no general signal framework — YAGNI).
+     *
+     * @public
+     */
+    objectiveThreadId?: string;
+}
+/**
+ * SE34 — the per-send completion criterion (see {@link SendOptions.completionCheck}).
+ *
+ * @public
+ */
+interface CompletionCheck {
+    /** What "complete" means for this send — fed to the judge as the goal. */
+    criteria: string;
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"`. */
+    judgeModel?: string;
+    /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY`. */
+    apiKey?: string;
+}
+/**
+ * SE34 — the resolved per-send completion verdict (see {@link RunResult.completionCheck}).
+ *
+ * @public
+ */
+interface CompletionCheckResult {
+    /** `true` when the judge ruled the send's reply satisfies the criteria. */
+    complete: boolean;
+    /** The judge's stated reason. */
+    reason: string;
+    /** `true` when the judge output could not be parsed — fail-safe `complete: false`. */
+    parseFailed: boolean;
 }
 /**
  * Handle to a single prompt submission.
@@ -1397,4 +1466,4 @@ interface GenerateRunResult<O> {
     };
 }
 
-export { type SDKStatusMessage as $, type AgentConversationTurn as A, type RunOperation as B, type CustomTool as C, type DoomLoopThresholds as D, type RunPermissionDeniedEvent as E, type RunRateLimitEvent as F, type GenerateOptions as G, type RunStatus as H, type ImageBlock as I, type RunTaskCompletedEvent as J, type RunTaskStartedEvent as K, type RunTaskUpdatedEvent as L, type ModelSelection as M, type RunToCompletionOptions as N, type OutputProcessorContext as O, type Processor as P, type RunToCompletionResult as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunToolProgressEvent as U, type RunTripwireEvent as V, type SDKAssistantMessage as W, type SDKImage as X, type SDKImageDimension as Y, type SDKObjectDelta as Z, type SDKRequestMessage as _, type McpServerConfig as a, type SDKSystemMessage as a0, type SDKTaskMessage as a1, type SDKThinkingMessage as a2, type SDKToolUseMessage as a3, type SDKUserMessage as a4, type SDKUserMessageEvent as a5, type SendOptions as a6, type ShellCommand as a7, type ShellConversationTurn as a8, type ShellOutput as a9, type ShellOutputDeltaUpdate as aa, type StepCompletedUpdate as ab, type StepStartedUpdate as ac, type StreamToCompletionResult as ad, type SummaryCompletedUpdate as ae, type SummaryStartedUpdate as af, type SummaryUpdate as ag, type TextBlock as ah, type TextDeltaUpdate as ai, type ThinkingCompletedUpdate as aj, type ThinkingDeltaUpdate as ak, type ThinkingMessage as al, type TokenDeltaUpdate as am, type TokenUsage as an, type ToolCall as ao, type ToolCallCompletedUpdate as ap, type ToolCallStartedUpdate as aq, type ToolContextMessage as ar, type ToolResult as as, type ToolResultGuardOptions as at, type ToolUseBlock as au, type TurnEndedUpdate as av, type UserMessage as aw, type UserMessageAppendedUpdate as ax, emitRunEvent as ay, type Run as b, type MessageOrigin as c, type AssistantMessage as d, type ConversationStep as e, type ConversationTurn as f, type CostBreakdown as g, type CostSource as h, type CostStatus as i, type GenerateRunResult as j, type InputProcessorContext as k, type InteractionUpdate as l, type McpAuthConfig as m, type McpHttpServerConfig as n, type McpOAuthConfig as o, type McpStdioServerConfig as p, type ModelParameterValue as q, type PartialToolCallUpdate as r, type ProcessorControls as s, type ProcessorTripwire as t, type ProcessorViolation as u, type RunCompactBoundaryEvent as v, type RunErrorDetail as w, type RunEvent as x, type RunEventSink as y, type RunGitInfo as z };
+export { type SDKImageDimension as $, type AgentConversationTurn as A, type RunEvent as B, type CustomTool as C, type DoomLoopThresholds as D, type RunEventSink as E, type RunGitInfo as F, type GenerateOptions as G, type RunOperation as H, type ImageBlock as I, type RunPermissionDeniedEvent as J, type RunRateLimitEvent as K, type RunStatus as L, type ModelSelection as M, type RunTaskCompletedEvent as N, type OutputProcessorContext as O, type Processor as P, type RunTaskStartedEvent as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunTaskUpdatedEvent as U, type RunToCompletionOptions as V, type RunToCompletionResult as W, type RunToolProgressEvent as X, type RunTripwireEvent as Y, type SDKAssistantMessage as Z, type SDKImage as _, type McpServerConfig as a, type SDKObjectDelta as a0, type SDKRequestMessage as a1, type SDKStatusMessage as a2, type SDKSystemMessage as a3, type SDKTaskMessage as a4, type SDKThinkingMessage as a5, type SDKToolUseMessage as a6, type SDKUserMessage as a7, type SDKUserMessageEvent as a8, type SendOptions as a9, type UserMessageAppendedUpdate as aA, emitRunEvent as aB, type ShellCommand as aa, type ShellConversationTurn as ab, type ShellOutput as ac, type ShellOutputDeltaUpdate as ad, type StepCompletedUpdate as ae, type StepStartedUpdate as af, type StreamToCompletionResult as ag, type SummaryCompletedUpdate as ah, type SummaryStartedUpdate as ai, type SummaryUpdate as aj, type TextBlock as ak, type TextDeltaUpdate as al, type ThinkingCompletedUpdate as am, type ThinkingDeltaUpdate as an, type ThinkingMessage as ao, type TokenDeltaUpdate as ap, type TokenUsage as aq, type ToolCall as ar, type ToolCallCompletedUpdate as as, type ToolCallStartedUpdate as at, type ToolContextMessage as au, type ToolResult as av, type ToolResultGuardOptions as aw, type ToolUseBlock as ax, type TurnEndedUpdate as ay, type UserMessage as az, type Run as b, type MessageOrigin as c, type AssistantMessage as d, type CompletionCheck as e, type CompletionCheckResult as f, type ConversationStep as g, type ConversationTurn as h, type CostBreakdown as i, type CostSource as j, type CostStatus as k, type GenerateRunResult as l, type InputProcessorContext as m, type InteractionUpdate as n, type McpAuthConfig as o, type McpHttpServerConfig as p, type McpOAuthConfig as q, type McpStdioServerConfig as r, type ModelParameterValue as s, type PartialToolCallUpdate as t, type ProcessorControls as u, type ProcessorTripwire as v, type ProcessorViolation as w, type RunCompactBoundaryEvent as x, type RunCompletionCheckEvent as y, type RunErrorDetail as z };

package/dist/types/agent.d.ts

@@ -404,6 +404,14 @@ export interface AgentOptions {
     outputProcessors?: readonly import("./processors.js").Processor[];
     /** Memory configuration. Persists durable facts; auto-recalled on send. */
     memory?: MemorySettings;
+    /**
+     * SE33 — standing goal config for a DURABLE, thread-scoped objective (Mastra
+     * Goals parity). Read when a durable objective (`setObjective`) is set: the
+     * per-objective values take precedence over this config, which takes
+     * precedence over the built-in defaults. The judge is the activation switch —
+     * with no `judgeModel` resolved, a standing objective is inert. ADR 0012.
+     */
+    goal?: import("./objective.js").AgentGoalConfig;
     /**
      * Inline custom tools. Local runtime only — cloud agents reject any non-empty
      * `tools` array. Handlers are not persisted; pass them again on resume.
@@ -703,7 +711,30 @@ export interface SDKAgent {
      *
      * @public
      */
-    runUntil?(goal: string, options?: import("./goal-events.js").GoalOptions): import("./goal-events.js").RunUntilIterator;
+    runUntil?(goal?: string, options?: import("./goal-events.js").GoalOptions): import("./goal-events.js").RunUntilIterator;
+    /**
+     * SE33 — set a DURABLE, thread-scoped objective persisted via the
+     * conversation storage (survives reload). Read by `runUntil()` when no
+     * explicit goal is passed. `threadId` is REQUIRED (the durability key); the
+     * call no-ops when the run is not memory-backed (the storage adapter omits the
+     * optional objective methods). Throws `ConfigurationError` on `maxRuns <= 0`.
+     * ADR 0012.
+     */
+    setObjective?(objective: string, opts: {
+        threadId: string;
+    } & import("./objective.js").DurableGoalOptions): Promise<void>;
+    /** SE33 — read the durable objective record for a thread (or `undefined`). */
+    getObjective?(opts: {
+        threadId: string;
+    }): Promise<import("./objective.js").ObjectiveRecord | undefined>;
+    /** SE33 — merge options into the active objective (only provided fields change; no-op if unset). */
+    updateObjectiveOptions?(opts: {
+        threadId: string;
+    } & import("./objective.js").DurableGoalOptions): Promise<void>;
+    /** SE33 — drop the durable objective for a thread. */
+    clearObjective?(opts: {
+        threadId: string;
+    }): Promise<void>;
     /**
      * Fork a short-lived sub-agent with parent's credentials + system
      * prompt byte-identical (ADR D112 — cache hit) and a restricted tool

package/dist/types/conversation-storage.d.ts

@@ -9,6 +9,7 @@
  *
  * @public
  */
+import type { ObjectiveRecord } from "./objective.js";
 /**
  * Persisted message envelope used by {@link ConversationStorageAdapter}.
  *
@@ -140,6 +141,28 @@ export interface ConversationStorageAdapter {
      * lazily. Adapters that cannot store side metadata MAY omit this.
      */
     setSessionMeta?(conversationId: string, patch: SessionMetaPatch): Promise<void>;
+    /**
+     * SE33 — optional: read the durable {@link ObjectiveRecord} for a conversation
+     * (the thread-scoped goal). Absent ⇒ the agent's objective methods no-op
+     * (typed degradation, same contract as `getSessionMeta`). ADR 0012 D1.
+     */
+    getObjectiveRecord?(conversationId: string): Promise<ObjectiveRecord | undefined>;
+    /**
+     * SE33 — optional: write (or, with `record: null`, CLEAR) the durable
+     * objective for a conversation. MUST create the record lazily. Adapters that
+     * cannot store side state MAY omit this. ADR 0012 D1.
+     */
+    setObjectiveRecord?(conversationId: string, record: ObjectiveRecord | null): Promise<void>;
+    /**
+     * SE33 — optional: ATOMIC read-modify-write of the durable objective. `mutate`
+     * receives the current record (or `undefined`) and returns the next record, or
+     * `null` to clear, or `undefined` to leave it unchanged. The whole get→mutate→set
+     * MUST run under the adapter's own concurrency guard (the FS adapter holds its
+     * file lock across the read AND the write) so concurrent progress write-backs
+     * on one thread cannot drop turns (TOCTOU). Adapters that omit it fall back to a
+     * non-atomic `getObjectiveRecord` + `setObjectiveRecord` pair. ADR 0012 D1.
+     */
+    updateObjectiveRecord?(conversationId: string, mutate: (current: ObjectiveRecord | undefined) => ObjectiveRecord | null | undefined): Promise<void>;
     /**
      * Optional: dispose underlying handles (close DB pool, etc.).
      * MUST be safe to call multiple times.

package/dist/types/goal-events.d.ts

@@ -86,6 +86,13 @@ export interface GoalOptions {
     judgeApiKey?: string;
     /** Optional subgoals fed to the judge prompt. */
     subgoals?: string[];
+    /**
+     * SE33 (ADR 0012) — resolve the goal from the durable thread-scoped
+     * objective when `runUntil()` is called with NO explicit goal. Also the
+     * key the loop writes `runsUsed` / `status` progress back to. Ignored when
+     * an explicit goal is passed (that path stays ephemeral).
+     */
+    threadId?: string;
     /**
      * Cancel mid-loop via `AbortController.signal`. The generator yields
      * a `status_change: paused` event and returns at the next turn

package/dist/types/index.d.ts

@@ -9,6 +9,7 @@ export type * from "./goal-events.js";
 export type * from "./mcp.js";
 export type * from "./memory-adapter.js";
 export type * from "./messages.js";
+export type * from "./objective.js";
 export type * from "./processors.js";
 export type * from "./providers.js";
 export type * from "./run.js";

package/dist/types/objective.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SE33 — the durable, thread-scoped objective (Mastra Goals parity, durable half).
+ *
+ * The SDK's `runUntil` goal loop (ADRs D115-D121) is per-call/transient. SE33
+ * persists an objective in conversation storage (via the optional
+ * `getObjectiveRecord`/`setObjectiveRecord` adapter methods) so it survives
+ * reloads, is managed via `Agent` methods, and is read by `runUntil` when no
+ * explicit goal is passed. See ADR 0012.
+ *
+ * @public
+ */
+/** Lifecycle status of a durable objective (ADR 0012 D2). */
+export type ObjectiveStatus = "active" | "done" | "paused";
+/**
+ * The per-objective override subset of goal options. Precedence (ADR 0012 D3):
+ * these `record.options` → the agent's standing `goal` config → built-in default.
+ * The `judgeModel` is the activation switch — with no judge resolved, the
+ * standing objective is inert (no scoring, no budget consumed).
+ */
+export interface DurableGoalOptions {
+    /** Max judge-gated turns before the loop stops (default 20 — the `runUntil` default). */
+    readonly maxRuns?: number;
+    /** Judge model identifier (e.g. `"openai/gpt-4o-mini"`). Absent ⇒ inherit from agent `goal` config. */
+    readonly judgeModel?: string;
+    /** Optional extra judge instruction appended to the default judge prompt. */
+    readonly prompt?: string;
+}
+/**
+ * A persisted objective record. Stored under the caller's `threadId` (the
+ * conversation key). `_schemaVersion` mirrors {@link import("./workflow.js").WorkflowSnapshot}
+ * for future migration (ADR 0012 D2).
+ */
+export interface ObjectiveRecord {
+    readonly _schemaVersion: 1;
+    readonly objective: string;
+    readonly options?: DurableGoalOptions;
+    readonly status: ObjectiveStatus;
+    readonly runsUsed: number;
+}
+/** The standing `goal` config on an agent (ADR 0012 D3). Read when a durable objective is set. */
+export interface AgentGoalConfig {
+    readonly judgeModel?: string;
+    readonly maxRuns?: number;
+    readonly prompt?: string;
+}