@theokit/sdk 4.18.0 → 4.19.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-gE8612p9.cjs';
 export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, m as ErrorCode, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-gE8612p9.cjs';
-import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as Plugin$1, m as ProviderProfile, I as InlineSkill, B as BudgetTracker, n as MemoryProvider, o as MemoryId, p as PreToolCallDecision, q as StepResult, r as SDKProvider } from './cron-DvP-E6Xx.cjs';
-export { s as ActiveMemoryPassArgs, t as ActiveMemoryPassResult, u as AgentMemory, v as BudgetCheck, w as BudgetTotal, x as BudgetUsageEvent, y as CloudEnv, z as CloudRepo, D as ContextBudget, E as ContextManagerKind, F as ContextSnapshot, H as ContextSource, J as ContextSourceStatus, K as CreateSkillSpec, N as Cron, O as CronCreateOptions, Q as CronGetOptions, R as CronJob, T as CronJobStatus, U as CronListOptions, V as CronOperationOptions, W as CronRunOptions, X as CronRuntime, Y as CronSchedulerStatus, Z as CronStartOptions, _ as GoalEvent, $ as GoalOptions, a0 as GoalResult, a1 as HookName, a2 as InvalidateCacheOptions, a3 as MemoryAdapter, a4 as MemoryAdapterCapabilities, a5 as MemoryContext, a6 as MemoryFact, a7 as MemoryProviderHandle, a8 as MemoryProviderInitOptions, a9 as MemoryRevision, aa as MemoryToolSchema, ab as MemoryTurnMessage, ac as PersonalityPreset, ad as PluginContext, ae as PostAssistantReplyContext, af as PreToolCallContext, ag as PreUserSendContext, ah as PreUserSendResult, ai as ProviderCapability, aj as ProviderRoute, ak as ProviderTransform, al as ProviderTransformContext, am as RecordSessionSummaryArgs, an as ResolvedProviderRoute, ao as RunUntilIterator, ap as SDKAgentPlugins, aq as SDKAgentSkillDetail, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SessionRecord, ax as SessionStore, ay as SettingSource, az as Skill, aA as SkillsResolver, aB as SkillsResolverContext, aC as SystemPromptContext, aD as SystemPromptMemoryFact, aE as SystemPromptSkillRef, aF as TelemetrySettings } from './cron-DvP-E6Xx.cjs';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as GoalOptions, m as GoalEvent, n as GoalResult, o as Plugin$1, p as ProviderProfile, I as InlineSkill, B as BudgetTracker, q as MemoryProvider, r as MemoryId, s as PreToolCallDecision, t as StepResult, u as SDKProvider } from './cron-DWc1r8m8.cjs';
+export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as BudgetCheck, z as BudgetTotal, D as BudgetUsageEvent, E as CloudEnv, F as CloudRepo, H as ContextBudget, J as ContextManagerKind, K as ContextSnapshot, N as ContextSource, O as ContextSourceStatus, Q as CreateSkillSpec, R as Cron, T as CronCreateOptions, U as CronGetOptions, V as CronJob, W as CronJobStatus, X as CronListOptions, Y as CronOperationOptions, Z as CronRunOptions, _ as CronRuntime, $ as CronSchedulerStatus, a0 as CronStartOptions, a1 as HookName, a2 as InvalidateCacheOptions, a3 as MemoryAdapter, a4 as MemoryAdapterCapabilities, a5 as MemoryContext, a6 as MemoryFact, a7 as MemoryProviderHandle, a8 as MemoryProviderInitOptions, a9 as MemoryRevision, aa as MemoryToolSchema, ab as MemoryTurnMessage, ac as PersonalityPreset, ad as PluginContext, ae as PostAssistantReplyContext, af as PreToolCallContext, ag as PreUserSendContext, ah as PreUserSendResult, ai as ProviderCapability, aj as ProviderRoute, ak as ProviderTransform, al as ProviderTransformContext, am as RecordSessionSummaryArgs, an as ResolvedProviderRoute, ao as RunUntilIterator, ap as SDKAgentPlugins, aq as SDKAgentSkillDetail, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SessionRecord, ax as SessionStore, ay as SettingSource, az as Skill, aA as SkillsResolver, aB as SkillsResolverContext, aC as SystemPromptContext, aD as SystemPromptMemoryFact, aE as SystemPromptSkillRef, aF as TelemetrySettings } from './cron-DWc1r8m8.cjs';
 import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, P as Processor, T as ToolResultContentBlock, c as PermissionMode, d as PermissionEngine, e as RunEventSink, S as SDKMessage } from './run-DFM1H2jW.cjs';
 export { A as AgentConversationTurn, f as AssistantMessage, g as CompletionCheck, h as CompletionCheckResult, i as ConversationStep, j as ConversationTurn, k as CostBreakdown, l as CostSource, m as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, n as GenerateRunResult, I as ImageBlock, o as InputProcessorContext, p as InteractionUpdate, q as McpAuthConfig, r as McpHttpServerConfig, s as McpOAuthConfig, t as McpStdioServerConfig, u as MessageOrigin, v as ModelParameterValue, O as OutputProcessorContext, w as PartialToolCallUpdate, x as PermissionAction, y as PermissionEngineOptions, z as PermissionRule, B as ProcessorControls, E as ProcessorTripwire, F as ProcessorViolation, H as RunCompactBoundaryEvent, J as RunCompletionCheckEvent, K as RunErrorDetail, L as RunEvent, N as RunGitInfo, Q as RunOperation, U as RunPermissionDeniedEvent, V as RunRateLimitEvent, W as RunStatus, X as RunTaskCompletedEvent, Y as RunTaskStartedEvent, Z as RunTaskUpdatedEvent, _ as RunToCompletionOptions, $ as RunToCompletionResult, a0 as RunToolProgressEvent, a1 as RunTripwireEvent, a2 as SDKAssistantMessage, a3 as SDKImage, a4 as SDKImageDimension, a5 as SDKObjectDelta, a6 as SDKRequestMessage, a7 as SDKStatusMessage, a8 as SDKSystemMessage, a9 as SDKTaskMessage, aa as SDKThinkingMessage, ab as SDKToolUseMessage, ac as SDKUserMessage, ad as SDKUserMessageEvent, ae as SendOptions, af as ShellCommand, ag as ShellConversationTurn, ah as ShellOutput, ai as ShellOutputDeltaUpdate, aj as StepCompletedUpdate, ak as StepStartedUpdate, al as StreamToCompletionResult, am as SummaryCompletedUpdate, an as SummaryStartedUpdate, ao as SummaryUpdate, ap as TextBlock, aq as TextDeltaUpdate, ar as ThinkingCompletedUpdate, as as ThinkingDeltaUpdate, at as ThinkingMessage, au as TokenDeltaUpdate, av as TokenUsage, aw as ToolCall, ax as ToolCallCompletedUpdate, ay as ToolCallStartedUpdate, az as ToolContextMessage, aA as ToolResult, aB as ToolResultGuardOptions, aC as ToolUseBlock, aD as TurnEndedUpdate, aE as UserMessage, aF as UserMessageAppendedUpdate, aG as applyMode, aH as emitRunEvent } from './run-DFM1H2jW.cjs';
 import * as zod from 'zod';
@@ -955,6 +955,106 @@ declare class UnicodeNormalizer {
     static create(opts?: UnicodeNormalizerOptions): Processor;
 }
 
+/**
+ * Judge call primitive (T2.2, ADRs D119-D121).
+ *
+ * Instantiates a short-lived auxiliary agent that evaluates whether a
+ * goal is satisfied. The auxiliary judge runs with `tools: []` and a
+ * cheap model (default `openai/gpt-4o-mini`) — see ADR D119. The judge
+ * model needs only API access; we read `OPENROUTER_API_KEY` directly
+ * from the environment (EC-A — single source of truth) and let the
+ * caller override via {@link JudgeOptions.apiKey} for Anthropic or
+ * direct-OpenAI environments.
+ *
+ * NOTE: judge aux agents created from inside a `forkAgent` context will
+ * inherit the parent fork's whitelist via AsyncLocalStorage (EC-J).
+ * `tools: []` keeps this benign today; future callers that add tools to
+ * a judge should be aware.
+ *
+ * @internal
+ */
+/** Inputs to the judge — pure data. */
+interface JudgeContext {
+    goal: string;
+    lastResponse: string;
+    subgoals?: string[];
+}
+/** Caller-supplied tuning knobs for the judge call. */
+interface JudgeOptions {
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"` (ADR D119). */
+    judgeModel?: string;
+    /** Override env. Default `process.env.OPENROUTER_API_KEY` (EC-A). */
+    apiKey?: string;
+}
+
+/**
+ * Public types for the judge subsystem (T2.1, ADR D120).
+ *
+ * @internal
+ */
+/** Outcome of {@link parseVerdict} / {@link judgeCallImpl}. */
+interface JudgeResult {
+    verdict: Verdict;
+    reason: string;
+    /**
+     * `true` when the underlying text did not start with one of the three
+     * canonical prefixes. The verdict is set to `"continue"` (fail-safe,
+     * ADR D121) to avoid stopping prematurely; callers track consecutive
+     * failures and bail via `maxConsecutiveJudgeFailures`.
+     */
+    parseFailed: boolean;
+}
+
+/**
+ * Goal-driven Ralph loop (T3.2, ADRs D115-D121).
+ *
+ * `runUntilImpl` is an `AsyncGenerator<GoalEvent, GoalResult, void>`:
+ * yields events as the loop progresses, returns the final result when
+ * the goal completes, fails, or is paused. The auxiliary judge model is
+ * injected via `deps.judge` so the generator stays free of the `Agent`
+ * façade import.
+ *
+ * EC-C fix: pre-aborted signals emit only `[paused]`, not `[active, paused]`.
+ * EC-D: `maxTurns: 0` is supported (vacuous yield active → failed).
+ *
+ * @internal
+ */
+
+/** DI contract: the judge is the only external touchpoint. */
+interface RunUntilDeps {
+    judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;
+}
+
+/**
+ * M56 (agent-builder goal transparency) — PUBLIC goal-loop driver for CUSTOM agent surfaces.
+ *
+ * `LocalAgent.runUntil` binds the goal loop to a registered local agent. Surfaces that route turns
+ * through their OWN transport (e.g. a TUI store facade, so every goal turn renders in the same
+ * timeline as a manual turn) need the SAME loop over a minimal `send → wait` shape. This export
+ * gives them exactly that: the canonical `runUntilImpl` (judge + continuation + token budget +
+ * Codex states) with the default judge wired from the DI registry.
+ *
+ * @public
+ */
+
+/** The minimal surface the goal loop drives — anything that can send a prompt and wait for it. */
+interface GoalLoopAgent {
+    send(prompt: string): Promise<{
+        wait(): Promise<{
+            result?: string;
+            usage?: {
+                totalTokens?: number;
+            };
+        }>;
+    }>;
+}
+/**
+ * Run the goal-driven loop (`send → judge → continuation`) over ANY `send → wait` surface.
+ * Identical semantics to `Agent.runUntil` (ADRs D115-D121 + M55 token budget / states).
+ * `depsOverride` is a test seam for injecting a fake judge.
+ */
+declare function runGoalLoop(agent: GoalLoopAgent, goal: string, options?: GoalOptions, depsOverride?: RunUntilDeps): AsyncGenerator<GoalEvent, GoalResult, void>;
+
 /**
  * Plugin contract — RUNTIME value + type re-exports (T1.1, ADRs D97-D101).
  *
@@ -2200,4 +2300,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, InlineSkill, JobQueue, type JobQueueOptions, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-CG2RpeW-.js';
 export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, m as ErrorCode, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-CG2RpeW-.js';
-import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as Plugin$1, m as ProviderProfile, I as InlineSkill, B as BudgetTracker, n as MemoryProvider, o as MemoryId, p as PreToolCallDecision, q as StepResult, r as SDKProvider } from './cron-DOW3f-Xu.js';
-export { s as ActiveMemoryPassArgs, t as ActiveMemoryPassResult, u as AgentMemory, v as BudgetCheck, w as BudgetTotal, x as BudgetUsageEvent, y as CloudEnv, z as CloudRepo, D as ContextBudget, E as ContextManagerKind, F as ContextSnapshot, H as ContextSource, J as ContextSourceStatus, K as CreateSkillSpec, N as Cron, O as CronCreateOptions, Q as CronGetOptions, R as CronJob, T as CronJobStatus, U as CronListOptions, V as CronOperationOptions, W as CronRunOptions, X as CronRuntime, Y as CronSchedulerStatus, Z as CronStartOptions, _ as GoalEvent, $ as GoalOptions, a0 as GoalResult, a1 as HookName, a2 as InvalidateCacheOptions, a3 as MemoryAdapter, a4 as MemoryAdapterCapabilities, a5 as MemoryContext, a6 as MemoryFact, a7 as MemoryProviderHandle, a8 as MemoryProviderInitOptions, a9 as MemoryRevision, aa as MemoryToolSchema, ab as MemoryTurnMessage, ac as PersonalityPreset, ad as PluginContext, ae as PostAssistantReplyContext, af as PreToolCallContext, ag as PreUserSendContext, ah as PreUserSendResult, ai as ProviderCapability, aj as ProviderRoute, ak as ProviderTransform, al as ProviderTransformContext, am as RecordSessionSummaryArgs, an as ResolvedProviderRoute, ao as RunUntilIterator, ap as SDKAgentPlugins, aq as SDKAgentSkillDetail, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SessionRecord, ax as SessionStore, ay as SettingSource, az as Skill, aA as SkillsResolver, aB as SkillsResolverContext, aC as SystemPromptContext, aD as SystemPromptMemoryFact, aE as SystemPromptSkillRef, aF as TelemetrySettings } from './cron-DOW3f-Xu.js';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as GoalOptions, m as GoalEvent, n as GoalResult, o as Plugin$1, p as ProviderProfile, I as InlineSkill, B as BudgetTracker, q as MemoryProvider, r as MemoryId, s as PreToolCallDecision, t as StepResult, u as SDKProvider } from './cron-BoMsrUs1.js';
+export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as BudgetCheck, z as BudgetTotal, D as BudgetUsageEvent, E as CloudEnv, F as CloudRepo, H as ContextBudget, J as ContextManagerKind, K as ContextSnapshot, N as ContextSource, O as ContextSourceStatus, Q as CreateSkillSpec, R as Cron, T as CronCreateOptions, U as CronGetOptions, V as CronJob, W as CronJobStatus, X as CronListOptions, Y as CronOperationOptions, Z as CronRunOptions, _ as CronRuntime, $ as CronSchedulerStatus, a0 as CronStartOptions, a1 as HookName, a2 as InvalidateCacheOptions, a3 as MemoryAdapter, a4 as MemoryAdapterCapabilities, a5 as MemoryContext, a6 as MemoryFact, a7 as MemoryProviderHandle, a8 as MemoryProviderInitOptions, a9 as MemoryRevision, aa as MemoryToolSchema, ab as MemoryTurnMessage, ac as PersonalityPreset, ad as PluginContext, ae as PostAssistantReplyContext, af as PreToolCallContext, ag as PreUserSendContext, ah as PreUserSendResult, ai as ProviderCapability, aj as ProviderRoute, ak as ProviderTransform, al as ProviderTransformContext, am as RecordSessionSummaryArgs, an as ResolvedProviderRoute, ao as RunUntilIterator, ap as SDKAgentPlugins, aq as SDKAgentSkillDetail, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SessionRecord, ax as SessionStore, ay as SettingSource, az as Skill, aA as SkillsResolver, aB as SkillsResolverContext, aC as SystemPromptContext, aD as SystemPromptMemoryFact, aE as SystemPromptSkillRef, aF as TelemetrySettings } from './cron-BoMsrUs1.js';
 import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, P as Processor, T as ToolResultContentBlock, c as PermissionMode, d as PermissionEngine, e as RunEventSink, S as SDKMessage } from './run-DFM1H2jW.js';
 export { A as AgentConversationTurn, f as AssistantMessage, g as CompletionCheck, h as CompletionCheckResult, i as ConversationStep, j as ConversationTurn, k as CostBreakdown, l as CostSource, m as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, n as GenerateRunResult, I as ImageBlock, o as InputProcessorContext, p as InteractionUpdate, q as McpAuthConfig, r as McpHttpServerConfig, s as McpOAuthConfig, t as McpStdioServerConfig, u as MessageOrigin, v as ModelParameterValue, O as OutputProcessorContext, w as PartialToolCallUpdate, x as PermissionAction, y as PermissionEngineOptions, z as PermissionRule, B as ProcessorControls, E as ProcessorTripwire, F as ProcessorViolation, H as RunCompactBoundaryEvent, J as RunCompletionCheckEvent, K as RunErrorDetail, L as RunEvent, N as RunGitInfo, Q as RunOperation, U as RunPermissionDeniedEvent, V as RunRateLimitEvent, W as RunStatus, X as RunTaskCompletedEvent, Y as RunTaskStartedEvent, Z as RunTaskUpdatedEvent, _ as RunToCompletionOptions, $ as RunToCompletionResult, a0 as RunToolProgressEvent, a1 as RunTripwireEvent, a2 as SDKAssistantMessage, a3 as SDKImage, a4 as SDKImageDimension, a5 as SDKObjectDelta, a6 as SDKRequestMessage, a7 as SDKStatusMessage, a8 as SDKSystemMessage, a9 as SDKTaskMessage, aa as SDKThinkingMessage, ab as SDKToolUseMessage, ac as SDKUserMessage, ad as SDKUserMessageEvent, ae as SendOptions, af as ShellCommand, ag as ShellConversationTurn, ah as ShellOutput, ai as ShellOutputDeltaUpdate, aj as StepCompletedUpdate, ak as StepStartedUpdate, al as StreamToCompletionResult, am as SummaryCompletedUpdate, an as SummaryStartedUpdate, ao as SummaryUpdate, ap as TextBlock, aq as TextDeltaUpdate, ar as ThinkingCompletedUpdate, as as ThinkingDeltaUpdate, at as ThinkingMessage, au as TokenDeltaUpdate, av as TokenUsage, aw as ToolCall, ax as ToolCallCompletedUpdate, ay as ToolCallStartedUpdate, az as ToolContextMessage, aA as ToolResult, aB as ToolResultGuardOptions, aC as ToolUseBlock, aD as TurnEndedUpdate, aE as UserMessage, aF as UserMessageAppendedUpdate, aG as applyMode, aH as emitRunEvent } from './run-DFM1H2jW.js';
 import * as zod from 'zod';
@@ -955,6 +955,106 @@ declare class UnicodeNormalizer {
     static create(opts?: UnicodeNormalizerOptions): Processor;
 }
 
+/**
+ * Judge call primitive (T2.2, ADRs D119-D121).
+ *
+ * Instantiates a short-lived auxiliary agent that evaluates whether a
+ * goal is satisfied. The auxiliary judge runs with `tools: []` and a
+ * cheap model (default `openai/gpt-4o-mini`) — see ADR D119. The judge
+ * model needs only API access; we read `OPENROUTER_API_KEY` directly
+ * from the environment (EC-A — single source of truth) and let the
+ * caller override via {@link JudgeOptions.apiKey} for Anthropic or
+ * direct-OpenAI environments.
+ *
+ * NOTE: judge aux agents created from inside a `forkAgent` context will
+ * inherit the parent fork's whitelist via AsyncLocalStorage (EC-J).
+ * `tools: []` keeps this benign today; future callers that add tools to
+ * a judge should be aware.
+ *
+ * @internal
+ */
+/** Inputs to the judge — pure data. */
+interface JudgeContext {
+    goal: string;
+    lastResponse: string;
+    subgoals?: string[];
+}
+/** Caller-supplied tuning knobs for the judge call. */
+interface JudgeOptions {
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"` (ADR D119). */
+    judgeModel?: string;
+    /** Override env. Default `process.env.OPENROUTER_API_KEY` (EC-A). */
+    apiKey?: string;
+}
+
+/**
+ * Public types for the judge subsystem (T2.1, ADR D120).
+ *
+ * @internal
+ */
+/** Outcome of {@link parseVerdict} / {@link judgeCallImpl}. */
+interface JudgeResult {
+    verdict: Verdict;
+    reason: string;
+    /**
+     * `true` when the underlying text did not start with one of the three
+     * canonical prefixes. The verdict is set to `"continue"` (fail-safe,
+     * ADR D121) to avoid stopping prematurely; callers track consecutive
+     * failures and bail via `maxConsecutiveJudgeFailures`.
+     */
+    parseFailed: boolean;
+}
+
+/**
+ * Goal-driven Ralph loop (T3.2, ADRs D115-D121).
+ *
+ * `runUntilImpl` is an `AsyncGenerator<GoalEvent, GoalResult, void>`:
+ * yields events as the loop progresses, returns the final result when
+ * the goal completes, fails, or is paused. The auxiliary judge model is
+ * injected via `deps.judge` so the generator stays free of the `Agent`
+ * façade import.
+ *
+ * EC-C fix: pre-aborted signals emit only `[paused]`, not `[active, paused]`.
+ * EC-D: `maxTurns: 0` is supported (vacuous yield active → failed).
+ *
+ * @internal
+ */
+
+/** DI contract: the judge is the only external touchpoint. */
+interface RunUntilDeps {
+    judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;
+}
+
+/**
+ * M56 (agent-builder goal transparency) — PUBLIC goal-loop driver for CUSTOM agent surfaces.
+ *
+ * `LocalAgent.runUntil` binds the goal loop to a registered local agent. Surfaces that route turns
+ * through their OWN transport (e.g. a TUI store facade, so every goal turn renders in the same
+ * timeline as a manual turn) need the SAME loop over a minimal `send → wait` shape. This export
+ * gives them exactly that: the canonical `runUntilImpl` (judge + continuation + token budget +
+ * Codex states) with the default judge wired from the DI registry.
+ *
+ * @public
+ */
+
+/** The minimal surface the goal loop drives — anything that can send a prompt and wait for it. */
+interface GoalLoopAgent {
+    send(prompt: string): Promise<{
+        wait(): Promise<{
+            result?: string;
+            usage?: {
+                totalTokens?: number;
+            };
+        }>;
+    }>;
+}
+/**
+ * Run the goal-driven loop (`send → judge → continuation`) over ANY `send → wait` surface.
+ * Identical semantics to `Agent.runUntil` (ADRs D115-D121 + M55 token budget / states).
+ * `depsOverride` is a test seam for injecting a fake judge.
+ */
+declare function runGoalLoop(agent: GoalLoopAgent, goal: string, options?: GoalOptions, depsOverride?: RunUntilDeps): AsyncGenerator<GoalEvent, GoalResult, void>;
+
 /**
  * Plugin contract — RUNTIME value + type re-exports (T1.1, ADRs D97-D101).
  *
@@ -2200,4 +2300,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, InlineSkill, JobQueue, type JobQueueOptions, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };

package/dist/index.js

@@ -7529,16 +7529,38 @@ async function* runUntilImpl(agent, goal, options, deps) {
   while (turn < maxTurns) {
     if (isAborted()) {
       yield { type: "status_change", status: "paused", reason: "aborted via AbortSignal" };
-      return { status: "paused", turnsUsed: turn, tokensUsed, finalResponse: lastResponse || void 0 };
+      return {
+        status: "paused",
+        turnsUsed: turn,
+        tokensUsed,
+        finalResponse: lastResponse || void 0
+      };
     }
     turn += 1;
     yield { type: "turn_start", turn, goal };
     const continuationPrompt = turn === 1 ? goal : composeContinuation(goal, lastResponse);
     const run = await agent.send(continuationPrompt);
+    const cancelOnAbort = () => {
+      void run.cancel?.();
+    };
+    if (signal !== void 0) {
+      if (signal.aborted) cancelOnAbort();
+      else signal.addEventListener("abort", cancelOnAbort, { once: true });
+    }
     const result = await run.wait();
+    if (signal !== void 0) signal.removeEventListener("abort", cancelOnAbort);
     lastResponse = result.result ?? "";
     const turnTokens = result.usage?.totalTokens;
     if (typeof turnTokens === "number") tokensUsed += turnTokens;
+    if (isAborted()) {
+      yield { type: "status_change", status: "paused", reason: "aborted via AbortSignal" };
+      return {
+        status: "paused",
+        turnsUsed: turn,
+        tokensUsed,
+        finalResponse: lastResponse || void 0
+      };
+    }
     yield { type: "agent_response", turn, content: lastResponse };
     const judgeOpts = {};
     if (options?.judgeModel !== void 0) judgeOpts.judgeModel = options.judgeModel;
@@ -7573,7 +7595,12 @@ async function* runUntilImpl(agent, goal, options, deps) {
     }
     if (judgment.verdict === "done") {
       yield { type: "status_change", status: "completed", reason: judgment.reason };
-      return { status: "completed", turnsUsed: turn, tokensUsed, finalResponse: lastResponse || void 0 };
+      return {
+        status: "completed",
+        turnsUsed: turn,
+        tokensUsed,
+        finalResponse: lastResponse || void 0
+      };
     }
     if (judgment.verdict === "skipped") {
       yield {
@@ -7581,7 +7608,12 @@ async function* runUntilImpl(agent, goal, options, deps) {
         status: "completed",
         reason: `skipped: ${judgment.reason}`
       };
-      return { status: "completed", turnsUsed: turn, tokensUsed, finalResponse: lastResponse || void 0 };
+      return {
+        status: "completed",
+        turnsUsed: turn,
+        tokensUsed,
+        finalResponse: lastResponse || void 0
+      };
     }
     if (tokenBudget !== void 0 && tokensUsed >= tokenBudget) {
       yield {
@@ -7589,7 +7621,12 @@ async function* runUntilImpl(agent, goal, options, deps) {
         status: "budget_limited",
         reason: `token budget (${tokenBudget}) reached: ${tokensUsed} used`
       };
-      return { status: "budget_limited", turnsUsed: turn, tokensUsed, finalResponse: lastResponse || void 0 };
+      return {
+        status: "budget_limited",
+        turnsUsed: turn,
+        tokensUsed,
+        finalResponse: lastResponse || void 0
+      };
     }
     yield { type: "continuation", turn, prompt: continuationPrompt };
   }
@@ -7598,7 +7635,12 @@ async function* runUntilImpl(agent, goal, options, deps) {
     status: "failed",
     reason: `max turns (${maxTurns}) exhausted`
   };
-  return { status: "failed", turnsUsed: turn, tokensUsed, finalResponse: lastResponse || void 0 };
+  return {
+    status: "failed",
+    turnsUsed: turn,
+    tokensUsed,
+    finalResponse: lastResponse || void 0
+  };
 }
 function composeContinuation(goal, lastResponse) {
   return [
@@ -22625,6 +22667,23 @@ async function updateJobStatus(jobId, enabled) {
   return updated;
 }
 
+// src/goal-loop.ts
+function runGoalLoop(agent, goal, options, depsOverride) {
+  async function* wrap() {
+    const { runUntilImpl: runUntilImpl2 } = await Promise.resolve().then(() => (init_run_until(), run_until_exports));
+    const deps = depsOverride ?? await (async () => {
+      const { judgeCallImpl: judgeCallImpl2 } = await Promise.resolve().then(() => (init_judge_call(), judge_call_exports));
+      const { getAgentFacade: getAgentFacade2 } = await Promise.resolve().then(() => (init_agent_factory_registry(), agent_factory_registry_exports));
+      const create = getAgentFacade2().create;
+      return {
+        judge: (ctx, opts) => judgeCallImpl2(ctx, opts, { create })
+      };
+    })();
+    return yield* runUntilImpl2(agent, goal, options, deps);
+  }
+  return wrap();
+}
+
 // src/define-provider.ts
 init_builtin();
 init_registry();
@@ -24460,6 +24519,6 @@ function safeStringify2(v) {
 // src/index.ts
 init_run_events();
 
-export { Agent, AgentBuilder, AgentDisposedError, AgentFactory, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, GenerateObjectError, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, NoopMemoryProvider, PermissionEngine, PermissionPlugin, Plugin, Provider, RateLimitError, Security, Skill, SkillReadTool, Squad, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, TokenLimiter, Tool, ToolError, UnicodeNormalizer, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, applyMode, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, emitRunEvent, estimateTokens2 as estimateTokens, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDisposedError, AgentFactory, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, GenerateObjectError, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, NoopMemoryProvider, PermissionEngine, PermissionPlugin, Plugin, Provider, RateLimitError, Security, Skill, SkillReadTool, Squad, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, TokenLimiter, Tool, ToolError, UnicodeNormalizer, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, applyMode, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, emitRunEvent, estimateTokens2 as estimateTokens, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map