@theokit/sdk 2.28.0 → 2.30.0

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;
+}

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

@@ -16,7 +16,7 @@
  *
  * @public
  */
-export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunTripwireEvent;
+export 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`
@@ -73,6 +73,17 @@ export 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}.
+ */
+export interface RunCompletionCheckEvent {
+    readonly type: "completion_check";
+    readonly complete: boolean;
+    readonly reason: string;
+}
 /** The conversation crossed a compaction boundary (history was summarized). */
 export interface RunCompactBoundaryEvent {
     readonly type: "compact_boundary";

package/dist/types/run.d.ts

@@ -155,6 +155,13 @@ export 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
@@ -427,6 +434,57 @@ export 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
+ */
+export 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
+ */
+export 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "2.28.0",
+  "version": "2.30.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheo/theokit-sdk#readme",
@@ -365,8 +365,8 @@
     "typedoc": "^0.28.19",
     "ws": "^8.18.0",
     "zod": "^4.0.0",
-    "@theokit/sdk-memory": "0.2.0",
-    "@theokit/sdk-handoff": "0.1.0"
+    "@theokit/sdk-handoff": "0.1.0",
+    "@theokit/sdk-memory": "0.2.0"
   },
   "scripts": {
     "build": "tsup && cp src/internal/providers/provider-catalog.json dist/provider-catalog.json",