@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/dist/core/foreground-recovery-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreground-recovery-controller.d.ts","sourceRoot":"","sources":["../../src/core/foreground-recovery-controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAmB,MAAM,2BAA2B,CAAC;AAEpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAG1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,KAAK,uBAAuB,GACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,MAAM,WAAW,gCAAgC;IAChD,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,EAAE,eAAe,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,EAAE,qBAAqB,CAAC;IACrC,gBAAgB,IAAI,MAAM,CAAC;IAC3B,IAAI,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAC3C,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,qBAAqB,IAAI,IAAI,CAAC;CAC9B;AAED,0FAA0F;AAC1F,qBAAa,4BAA4B;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4B;IAC5D,OAAO,CAAC,oBAAoB,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmC;IAExD,YAAY,IAAI,EAAE,gCAAgC,EA4BjD;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,UAAU,IAAI,IAAI,CAEjB;IAED,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErC;IAED,iBAAiB,IAAI,yBAAyB,CAE7C;IAED,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAQhD;IAED,sBAAsB,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,EAAE;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC,GAAG,OAAO,CAQjF;IAEK,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC,CA4B3C;IAED,OAAO,CAAC,sBAAsB;CAQ9B","sourcesContent":["import type { Agent, AgentEvent, ClassifiedError } from \"@caupulican/pi-agent-core\";\nimport { classifyFailure, DEFAULT_RETRY_POLICY, RetryController } from \"@caupulican/pi-agent-core\";\nimport type { AssistantMessage } from \"@caupulican/pi-ai\";\nimport { isContextOverflow } from \"@caupulican/pi-ai\";\nimport { BillingFailoverController, ExhaustedProviderRegistry } from \"./billing-failover-controller.ts\";\nimport type { FailureCorpusRecorder } from \"./failure-corpus.ts\";\nimport type { ModelRegistry } from \"./model-registry.ts\";\nimport type { ModelRouterFailoverStatus } from \"./model-router/status.ts\";\nimport type { SettingsManager } from \"./settings-manager.ts\";\n\ntype ForegroundRecoveryEvent =\n\t| { type: \"warning\"; message: string }\n\t| { type: \"auto_retry_start\"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }\n\t| { type: \"auto_retry_end\"; success: boolean; attempt: number; finalError?: string };\n\nexport interface ForegroundRecoveryControllerDeps {\n\tagent: Agent;\n\tsettingsManager: SettingsManager;\n\tmodelRegistry: ModelRegistry;\n\tfailureCorpus: FailureCorpusRecorder;\n\tgetContextWindow(): number;\n\temit(event: ForegroundRecoveryEvent): void;\n\tcheckCompaction(message: AssistantMessage): Promise<boolean>;\n\tonSuccessfulAssistant(): void;\n}\n\n/** Owns foreground retry/failover/compaction recovery ordering and its response latch. */\nexport class ForegroundRecoveryController {\n\tprivate readonly retry: RetryController;\n\tprivate readonly billingFailover: BillingFailoverController;\n\tprivate lastAssistantMessage: AssistantMessage | undefined;\n\tprivate readonly deps: ForegroundRecoveryControllerDeps;\n\n\tconstructor(deps: ForegroundRecoveryControllerDeps) {\n\t\tthis.deps = deps;\n\t\tthis.retry = new RetryController(\n\t\t\tdeps.agent,\n\t\t\t() => {\n\t\t\t\tconst retry = deps.settingsManager.getRetrySettings();\n\t\t\t\treturn {\n\t\t\t\t\tenabled: retry.enabled,\n\t\t\t\t\tmaxAttempts: retry.maxRetries,\n\t\t\t\t\tbaseDelayMs: retry.baseDelayMs,\n\t\t\t\t\tmaxDelayMs: DEFAULT_RETRY_POLICY.maxDelayMs,\n\t\t\t\t\tjitterRatio: 0,\n\t\t\t\t};\n\t\t\t},\n\t\t\t{\n\t\t\t\tonRetryStart: (info) => deps.emit({ type: \"auto_retry_start\", ...info }),\n\t\t\t\tonRetryEnd: (info) => deps.emit({ type: \"auto_retry_end\", ...info }),\n\t\t\t},\n\t\t\tdeps.getContextWindow,\n\t\t);\n\t\tthis.billingFailover = new BillingFailoverController({\n\t\t\tagent: deps.agent,\n\t\t\tmodelRegistry: deps.modelRegistry,\n\t\t\texhausted: new ExhaustedProviderRegistry(),\n\t\t\tsubscriptionHop: deps.settingsManager.getFailoverSettings().subscriptionHop,\n\t\t\temit: deps.emit,\n\t\t\trecordFailure: (record) => deps.failureCorpus.record(record),\n\t\t});\n\t}\n\n\tget attempt(): number {\n\t\treturn this.retry.attempt;\n\t}\n\n\tget isRetrying(): boolean {\n\t\treturn this.retry.isRetrying;\n\t}\n\n\tabortRetry(): void {\n\t\tthis.retry.abort();\n\t}\n\n\tisModelExhausted(ref: string): boolean {\n\t\treturn this.billingFailover.isExhausted(ref);\n\t}\n\n\tgetFailoverStatus(): ModelRouterFailoverStatus {\n\t\treturn this.billingFailover.getStatus();\n\t}\n\n\tobserveAssistant(message: AssistantMessage): void {\n\t\tthis.lastAssistantMessage = message;\n\t\tif (message.stopReason === \"error\") return;\n\t\tthis.deps.onSuccessfulAssistant();\n\t\tif (this.retry.attempt > 0) {\n\t\t\tthis.deps.emit({ type: \"auto_retry_end\", success: true, attempt: this.retry.attempt });\n\t\t\tthis.retry.reset();\n\t\t}\n\t}\n\n\twillRetryAfterAgentEnd(event: Extract<AgentEvent, { type: \"agent_end\" }>): boolean {\n\t\tconst settings = this.deps.settingsManager.getRetrySettings();\n\t\tif (!settings.enabled || this.retry.attempt >= settings.maxRetries) return false;\n\t\tfor (let index = event.messages.length - 1; index >= 0; index--) {\n\t\t\tconst message = event.messages[index];\n\t\t\tif (message.role === \"assistant\") return this.classifyAssistantError(message)?.retryable ?? false;\n\t\t}\n\t\treturn false;\n\t}\n\n\tasync handlePostAgentRun(): Promise<boolean> {\n\t\tconst message = this.lastAssistantMessage;\n\t\tthis.lastAssistantMessage = undefined;\n\t\tif (!message) return false;\n\n\t\tconst classified = this.classifyAssistantError(message);\n\t\tif (classified) {\n\t\t\tthis.deps.failureCorpus.record({\n\t\t\t\tprovider: message.provider,\n\t\t\t\tmodelId: message.model,\n\t\t\t\tmessage: message.errorMessage ?? \"\",\n\t\t\t\tclassified,\n\t\t\t});\n\t\t}\n\t\tif (classified?.retryable && (await this.retry.prepareRetry(message))) return true;\n\t\tif (await this.billingFailover.handleAssistantError(message, classified)) return false;\n\n\t\tif (message.stopReason === \"error\" && this.retry.attempt > 0) {\n\t\t\tthis.deps.emit({\n\t\t\t\ttype: \"auto_retry_end\",\n\t\t\t\tsuccess: false,\n\t\t\t\tattempt: this.retry.attempt,\n\t\t\t\tfinalError: message.errorMessage,\n\t\t\t});\n\t\t\tthis.retry.reset();\n\t\t}\n\t\tif (await this.deps.checkCompaction(message)) return true;\n\t\treturn this.deps.agent.hasQueuedMessages();\n\t}\n\n\tprivate classifyAssistantError(message: AssistantMessage): ClassifiedError | undefined {\n\t\tif (message.stopReason !== \"error\" || !message.errorMessage) return undefined;\n\t\treturn classifyFailure({\n\t\t\tmessage: message.errorMessage,\n\t\t\tcontextOverflow: isContextOverflow(message, this.deps.getContextWindow()),\n\t\t\tprovider: message.provider,\n\t\t});\n\t}\n}\n"]}

package/dist/core/foreground-recovery-controller.js

@@ -0,0 +1,111 @@
+import { classifyFailure, DEFAULT_RETRY_POLICY, RetryController } from "@caupulican/pi-agent-core";
+import { isContextOverflow } from "@caupulican/pi-ai";
+import { BillingFailoverController, ExhaustedProviderRegistry } from "./billing-failover-controller.js";
+/** Owns foreground retry/failover/compaction recovery ordering and its response latch. */
+export class ForegroundRecoveryController {
+    retry;
+    billingFailover;
+    lastAssistantMessage;
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+        this.retry = new RetryController(deps.agent, () => {
+            const retry = deps.settingsManager.getRetrySettings();
+            return {
+                enabled: retry.enabled,
+                maxAttempts: retry.maxRetries,
+                baseDelayMs: retry.baseDelayMs,
+                maxDelayMs: DEFAULT_RETRY_POLICY.maxDelayMs,
+                jitterRatio: 0,
+            };
+        }, {
+            onRetryStart: (info) => deps.emit({ type: "auto_retry_start", ...info }),
+            onRetryEnd: (info) => deps.emit({ type: "auto_retry_end", ...info }),
+        }, deps.getContextWindow);
+        this.billingFailover = new BillingFailoverController({
+            agent: deps.agent,
+            modelRegistry: deps.modelRegistry,
+            exhausted: new ExhaustedProviderRegistry(),
+            subscriptionHop: deps.settingsManager.getFailoverSettings().subscriptionHop,
+            emit: deps.emit,
+            recordFailure: (record) => deps.failureCorpus.record(record),
+        });
+    }
+    get attempt() {
+        return this.retry.attempt;
+    }
+    get isRetrying() {
+        return this.retry.isRetrying;
+    }
+    abortRetry() {
+        this.retry.abort();
+    }
+    isModelExhausted(ref) {
+        return this.billingFailover.isExhausted(ref);
+    }
+    getFailoverStatus() {
+        return this.billingFailover.getStatus();
+    }
+    observeAssistant(message) {
+        this.lastAssistantMessage = message;
+        if (message.stopReason === "error")
+            return;
+        this.deps.onSuccessfulAssistant();
+        if (this.retry.attempt > 0) {
+            this.deps.emit({ type: "auto_retry_end", success: true, attempt: this.retry.attempt });
+            this.retry.reset();
+        }
+    }
+    willRetryAfterAgentEnd(event) {
+        const settings = this.deps.settingsManager.getRetrySettings();
+        if (!settings.enabled || this.retry.attempt >= settings.maxRetries)
+            return false;
+        for (let index = event.messages.length - 1; index >= 0; index--) {
+            const message = event.messages[index];
+            if (message.role === "assistant")
+                return this.classifyAssistantError(message)?.retryable ?? false;
+        }
+        return false;
+    }
+    async handlePostAgentRun() {
+        const message = this.lastAssistantMessage;
+        this.lastAssistantMessage = undefined;
+        if (!message)
+            return false;
+        const classified = this.classifyAssistantError(message);
+        if (classified) {
+            this.deps.failureCorpus.record({
+                provider: message.provider,
+                modelId: message.model,
+                message: message.errorMessage ?? "",
+                classified,
+            });
+        }
+        if (classified?.retryable && (await this.retry.prepareRetry(message)))
+            return true;
+        if (await this.billingFailover.handleAssistantError(message, classified))
+            return false;
+        if (message.stopReason === "error" && this.retry.attempt > 0) {
+            this.deps.emit({
+                type: "auto_retry_end",
+                success: false,
+                attempt: this.retry.attempt,
+                finalError: message.errorMessage,
+            });
+            this.retry.reset();
+        }
+        if (await this.deps.checkCompaction(message))
+            return true;
+        return this.deps.agent.hasQueuedMessages();
+    }
+    classifyAssistantError(message) {
+        if (message.stopReason !== "error" || !message.errorMessage)
+            return undefined;
+        return classifyFailure({
+            message: message.errorMessage,
+            contextOverflow: isContextOverflow(message, this.deps.getContextWindow()),
+            provider: message.provider,
+        });
+    }
+}
+//# sourceMappingURL=foreground-recovery-controller.js.map

package/dist/core/foreground-recovery-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreground-recovery-controller.js","sourceRoot":"","sources":["../../src/core/foreground-recovery-controller.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Agent, AgentEvent, ClassifiedError } from \"@caupulican/pi-agent-core\";\nimport { classifyFailure, DEFAULT_RETRY_POLICY, RetryController } from \"@caupulican/pi-agent-core\";\nimport type { AssistantMessage } from \"@caupulican/pi-ai\";\nimport { isContextOverflow } from \"@caupulican/pi-ai\";\nimport { BillingFailoverController, ExhaustedProviderRegistry } from \"./billing-failover-controller.ts\";\nimport type { FailureCorpusRecorder } from \"./failure-corpus.ts\";\nimport type { ModelRegistry } from \"./model-registry.ts\";\nimport type { ModelRouterFailoverStatus } from \"./model-router/status.ts\";\nimport type { SettingsManager } from \"./settings-manager.ts\";\n\ntype ForegroundRecoveryEvent =\n\t| { type: \"warning\"; message: string }\n\t| { type: \"auto_retry_start\"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }\n\t| { type: \"auto_retry_end\"; success: boolean; attempt: number; finalError?: string };\n\nexport interface ForegroundRecoveryControllerDeps {\n\tagent: Agent;\n\tsettingsManager: SettingsManager;\n\tmodelRegistry: ModelRegistry;\n\tfailureCorpus: FailureCorpusRecorder;\n\tgetContextWindow(): number;\n\temit(event: ForegroundRecoveryEvent): void;\n\tcheckCompaction(message: AssistantMessage): Promise<boolean>;\n\tonSuccessfulAssistant(): void;\n}\n\n/** Owns foreground retry/failover/compaction recovery ordering and its response latch. */\nexport class ForegroundRecoveryController {\n\tprivate readonly retry: RetryController;\n\tprivate readonly billingFailover: BillingFailoverController;\n\tprivate lastAssistantMessage: AssistantMessage | undefined;\n\tprivate readonly deps: ForegroundRecoveryControllerDeps;\n\n\tconstructor(deps: ForegroundRecoveryControllerDeps) {\n\t\tthis.deps = deps;\n\t\tthis.retry = new RetryController(\n\t\t\tdeps.agent,\n\t\t\t() => {\n\t\t\t\tconst retry = deps.settingsManager.getRetrySettings();\n\t\t\t\treturn {\n\t\t\t\t\tenabled: retry.enabled,\n\t\t\t\t\tmaxAttempts: retry.maxRetries,\n\t\t\t\t\tbaseDelayMs: retry.baseDelayMs,\n\t\t\t\t\tmaxDelayMs: DEFAULT_RETRY_POLICY.maxDelayMs,\n\t\t\t\t\tjitterRatio: 0,\n\t\t\t\t};\n\t\t\t},\n\t\t\t{\n\t\t\t\tonRetryStart: (info) => deps.emit({ type: \"auto_retry_start\", ...info }),\n\t\t\t\tonRetryEnd: (info) => deps.emit({ type: \"auto_retry_end\", ...info }),\n\t\t\t},\n\t\t\tdeps.getContextWindow,\n\t\t);\n\t\tthis.billingFailover = new BillingFailoverController({\n\t\t\tagent: deps.agent,\n\t\t\tmodelRegistry: deps.modelRegistry,\n\t\t\texhausted: new ExhaustedProviderRegistry(),\n\t\t\tsubscriptionHop: deps.settingsManager.getFailoverSettings().subscriptionHop,\n\t\t\temit: deps.emit,\n\t\t\trecordFailure: (record) => deps.failureCorpus.record(record),\n\t\t});\n\t}\n\n\tget attempt(): number {\n\t\treturn this.retry.attempt;\n\t}\n\n\tget isRetrying(): boolean {\n\t\treturn this.retry.isRetrying;\n\t}\n\n\tabortRetry(): void {\n\t\tthis.retry.abort();\n\t}\n\n\tisModelExhausted(ref: string): boolean {\n\t\treturn this.billingFailover.isExhausted(ref);\n\t}\n\n\tgetFailoverStatus(): ModelRouterFailoverStatus {\n\t\treturn this.billingFailover.getStatus();\n\t}\n\n\tobserveAssistant(message: AssistantMessage): void {\n\t\tthis.lastAssistantMessage = message;\n\t\tif (message.stopReason === \"error\") return;\n\t\tthis.deps.onSuccessfulAssistant();\n\t\tif (this.retry.attempt > 0) {\n\t\t\tthis.deps.emit({ type: \"auto_retry_end\", success: true, attempt: this.retry.attempt });\n\t\t\tthis.retry.reset();\n\t\t}\n\t}\n\n\twillRetryAfterAgentEnd(event: Extract<AgentEvent, { type: \"agent_end\" }>): boolean {\n\t\tconst settings = this.deps.settingsManager.getRetrySettings();\n\t\tif (!settings.enabled || this.retry.attempt >= settings.maxRetries) return false;\n\t\tfor (let index = event.messages.length - 1; index >= 0; index--) {\n\t\t\tconst message = event.messages[index];\n\t\t\tif (message.role === \"assistant\") return this.classifyAssistantError(message)?.retryable ?? false;\n\t\t}\n\t\treturn false;\n\t}\n\n\tasync handlePostAgentRun(): Promise<boolean> {\n\t\tconst message = this.lastAssistantMessage;\n\t\tthis.lastAssistantMessage = undefined;\n\t\tif (!message) return false;\n\n\t\tconst classified = this.classifyAssistantError(message);\n\t\tif (classified) {\n\t\t\tthis.deps.failureCorpus.record({\n\t\t\t\tprovider: message.provider,\n\t\t\t\tmodelId: message.model,\n\t\t\t\tmessage: message.errorMessage ?? \"\",\n\t\t\t\tclassified,\n\t\t\t});\n\t\t}\n\t\tif (classified?.retryable && (await this.retry.prepareRetry(message))) return true;\n\t\tif (await this.billingFailover.handleAssistantError(message, classified)) return false;\n\n\t\tif (message.stopReason === \"error\" && this.retry.attempt > 0) {\n\t\t\tthis.deps.emit({\n\t\t\t\ttype: \"auto_retry_end\",\n\t\t\t\tsuccess: false,\n\t\t\t\tattempt: this.retry.attempt,\n\t\t\t\tfinalError: message.errorMessage,\n\t\t\t});\n\t\t\tthis.retry.reset();\n\t\t}\n\t\tif (await this.deps.checkCompaction(message)) return true;\n\t\treturn this.deps.agent.hasQueuedMessages();\n\t}\n\n\tprivate classifyAssistantError(message: AssistantMessage): ClassifiedError | undefined {\n\t\tif (message.stopReason !== \"error\" || !message.errorMessage) return undefined;\n\t\treturn classifyFailure({\n\t\t\tmessage: message.errorMessage,\n\t\t\tcontextOverflow: isContextOverflow(message, this.deps.getContextWindow()),\n\t\t\tprovider: message.provider,\n\t\t});\n\t}\n}\n"]}

package/dist/core/gateways/channel-provider.d.ts

@@ -60,6 +60,9 @@ export declare class GatewayRegistry {
     private readonly schedulers;
     private started;
     private inboundHandler;
+    private readonly pendingLifecycle;
+    private trackLifecycle;
+    private drainLifecycle;
     registerChannel(provider: ChannelProvider): void;
     registerScheduler(provider: JobSchedulerProvider): void;
     getChannel(name: string): ChannelProvider | undefined;

package/dist/core/gateways/channel-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel-provider.d.ts","sourceRoot":"","sources":["../../../src/core/gateways/channel-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC9B,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,mEAAmE;AACnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEtF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,KAAK,CAAC,SAAS,EAAE,qBAAqB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,gDAAgD;IAChD,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,4CAA4C;IAC5C,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,kCAAkC;AAClC,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,GAAG,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2C;IACtE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAmC;IAEzD,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAM/C;IAED,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAKtD;IAED,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEpD;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,2FAA2F;IACrF,KAAK,CAAC,SAAS,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB3D;IAED,uFAAuF;IACjF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAa1B;CACD","sourcesContent":["/**\n * Interface-driven gateways & scheduling (adaptive-agent design R8).\n *\n * pi does NOT bake transports (Slack/Discord/email/webhooks) or a cron tick loop into the core — that\n * would bloat the agent and couple it to deployment concerns. Instead it exposes two provider contracts\n * that a deployment wrapper (server, headless runner) implements and registers; the core only manages\n * their lifecycle. This keeps the CLI/agent transport- and schedule-agnostic while still offering a\n * first-class, uniform extension point.\n */\n\n/** A message arriving from / sent to an external channel (gateway). */\nexport interface ChannelMessage {\n\t/** Stable conversation/session key for this channel (e.g. `slack_C123`). */\n\tconversationKey: string;\n\t/** Message text. */\n\ttext: string;\n\t/** Optional opaque metadata the provider round-trips. */\n\tmeta?: Record<string, unknown>;\n}\n\n/** Handler the core supplies to a channel for inbound messages. */\nexport type ChannelInboundHandler = (message: ChannelMessage) => void | Promise<void>;\n\n/**\n * A transport channel (Telegram/Slack/email/webhook/...). Implemented by a deployment wrapper and\n * registered via {@link GatewayRegistry}. The core starts it (handing it an inbound handler) and stops\n * it on shutdown; it never imports any transport SDK itself.\n */\nexport interface ChannelProvider {\n\treadonly name: string;\n\t/** Begin listening; deliver inbound messages to `onInbound`. */\n\tstart(onInbound: ChannelInboundHandler): void | Promise<void>;\n\t/** Send an outbound message on this channel. */\n\tsend(message: ChannelMessage): void | Promise<void>;\n\t/** Stop listening and release resources. */\n\tstop(): void | Promise<void>;\n}\n\n/** A scheduled job definition. */\nexport interface ScheduledJob {\n\tid: string;\n\t/** Cron expression or interval spec the provider understands. */\n\tschedule: string;\n\t/** Invoked when the job fires. */\n\trun: () => void | Promise<void>;\n}\n\n/**\n * A scheduler (cron-like). Implemented by a deployment wrapper and registered via\n * {@link GatewayRegistry}. The core registers jobs + starts/stops it; it owns no tick loop itself.\n */\nexport interface JobSchedulerProvider {\n\treadonly name: string;\n\tschedule(job: ScheduledJob): void;\n\tstart(): void | Promise<void>;\n\tstop(): void | Promise<void>;\n}\n\n/**\n * Holds registered channel + scheduler providers and drives their lifecycle. A session starts all\n * registered providers when it binds and stops them on dispose. Registration is additive and idempotent\n * by provider name (last registration wins).\n */\nexport class GatewayRegistry {\n\tprivate readonly channels = new Map<string, ChannelProvider>();\n\tprivate readonly schedulers = new Map<string, JobSchedulerProvider>();\n\tprivate started = false;\n\tprivate inboundHandler: ChannelInboundHandler = () => {};\n\n\tregisterChannel(provider: ChannelProvider): void {\n\t\t// Stop a same-named provider being replaced so its listeners/sockets don't leak (Bug #17).\n\t\tconst existing = this.channels.get(provider.name);\n\t\tif (existing && existing !== provider) void Promise.resolve(existing.stop()).catch(() => {});\n\t\tthis.channels.set(provider.name, provider);\n\t\tif (this.started) void Promise.resolve(provider.start(this.inboundHandler)).catch(() => {});\n\t}\n\n\tregisterScheduler(provider: JobSchedulerProvider): void {\n\t\tconst existing = this.schedulers.get(provider.name);\n\t\tif (existing && existing !== provider) void Promise.resolve(existing.stop()).catch(() => {});\n\t\tthis.schedulers.set(provider.name, provider);\n\t\tif (this.started) void Promise.resolve(provider.start()).catch(() => {});\n\t}\n\n\tgetChannel(name: string): ChannelProvider | undefined {\n\t\treturn this.channels.get(name);\n\t}\n\n\tget channelCount(): number {\n\t\treturn this.channels.size;\n\t}\n\n\tget schedulerCount(): number {\n\t\treturn this.schedulers.size;\n\t}\n\n\t/** Start every registered provider; inbound channel messages are routed to `onInbound`. */\n\tasync start(onInbound: ChannelInboundHandler): Promise<void> {\n\t\tif (this.started) return;\n\t\tthis.started = true;\n\t\tthis.inboundHandler = onInbound;\n\t\tfor (const channel of this.channels.values()) {\n\t\t\ttry {\n\t\t\t\tawait channel.start(onInbound);\n\t\t\t} catch {\n\t\t\t\t// a failing channel must not block the others\n\t\t\t}\n\t\t}\n\t\tfor (const scheduler of this.schedulers.values()) {\n\t\t\ttry {\n\t\t\t\tawait scheduler.start();\n\t\t\t} catch {}\n\t\t}\n\t}\n\n\t/** Stop every registered provider. Best-effort; always leaves the registry stopped. */\n\tasync stop(): Promise<void> {\n\t\tif (!this.started) return;\n\t\tthis.started = false;\n\t\tfor (const channel of this.channels.values()) {\n\t\t\ttry {\n\t\t\t\tawait channel.stop();\n\t\t\t} catch {}\n\t\t}\n\t\tfor (const scheduler of this.schedulers.values()) {\n\t\t\ttry {\n\t\t\t\tawait scheduler.stop();\n\t\t\t} catch {}\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"channel-provider.d.ts","sourceRoot":"","sources":["../../../src/core/gateways/channel-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC9B,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,mEAAmE;AACnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEtF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,KAAK,CAAC,SAAS,EAAE,qBAAqB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,gDAAgD;IAChD,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,4CAA4C;IAC5C,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,kCAAkC;AAClC,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,GAAG,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2C;IACtE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAmC;IACzD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA4B;IAE7D,OAAO,CAAC,cAAc;YAWR,cAAc;IAM5B,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAM/C;IAED,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAKtD;IAED,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEpD;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,2FAA2F;IACrF,KAAK,CAAC,SAAS,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3D;IAED,uFAAuF;IACjF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAmB1B;CACD","sourcesContent":["/**\n * Interface-driven gateways & scheduling (adaptive-agent design R8).\n *\n * pi does NOT bake transports (Slack/Discord/email/webhooks) or a cron tick loop into the core — that\n * would bloat the agent and couple it to deployment concerns. Instead it exposes two provider contracts\n * that a deployment wrapper (server, headless runner) implements and registers; the core only manages\n * their lifecycle. This keeps the CLI/agent transport- and schedule-agnostic while still offering a\n * first-class, uniform extension point.\n */\n\n/** A message arriving from / sent to an external channel (gateway). */\nexport interface ChannelMessage {\n\t/** Stable conversation/session key for this channel (e.g. `slack_C123`). */\n\tconversationKey: string;\n\t/** Message text. */\n\ttext: string;\n\t/** Optional opaque metadata the provider round-trips. */\n\tmeta?: Record<string, unknown>;\n}\n\n/** Handler the core supplies to a channel for inbound messages. */\nexport type ChannelInboundHandler = (message: ChannelMessage) => void | Promise<void>;\n\n/**\n * A transport channel (Telegram/Slack/email/webhook/...). Implemented by a deployment wrapper and\n * registered via {@link GatewayRegistry}. The core starts it (handing it an inbound handler) and stops\n * it on shutdown; it never imports any transport SDK itself.\n */\nexport interface ChannelProvider {\n\treadonly name: string;\n\t/** Begin listening; deliver inbound messages to `onInbound`. */\n\tstart(onInbound: ChannelInboundHandler): void | Promise<void>;\n\t/** Send an outbound message on this channel. */\n\tsend(message: ChannelMessage): void | Promise<void>;\n\t/** Stop listening and release resources. */\n\tstop(): void | Promise<void>;\n}\n\n/** A scheduled job definition. */\nexport interface ScheduledJob {\n\tid: string;\n\t/** Cron expression or interval spec the provider understands. */\n\tschedule: string;\n\t/** Invoked when the job fires. */\n\trun: () => void | Promise<void>;\n}\n\n/**\n * A scheduler (cron-like). Implemented by a deployment wrapper and registered via\n * {@link GatewayRegistry}. The core registers jobs + starts/stops it; it owns no tick loop itself.\n */\nexport interface JobSchedulerProvider {\n\treadonly name: string;\n\tschedule(job: ScheduledJob): void;\n\tstart(): void | Promise<void>;\n\tstop(): void | Promise<void>;\n}\n\n/**\n * Holds registered channel + scheduler providers and drives their lifecycle. A session starts all\n * registered providers when it binds and stops them on dispose. Registration is additive and idempotent\n * by provider name (last registration wins).\n */\nexport class GatewayRegistry {\n\tprivate readonly channels = new Map<string, ChannelProvider>();\n\tprivate readonly schedulers = new Map<string, JobSchedulerProvider>();\n\tprivate started = false;\n\tprivate inboundHandler: ChannelInboundHandler = () => {};\n\tprivate readonly pendingLifecycle = new Set<Promise<void>>();\n\n\tprivate trackLifecycle(operation: () => void | Promise<void>): void {\n\t\tlet pending: Promise<void>;\n\t\ttry {\n\t\t\tpending = Promise.resolve(operation()).catch(() => {});\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t\tthis.pendingLifecycle.add(pending);\n\t\tvoid pending.finally(() => this.pendingLifecycle.delete(pending));\n\t}\n\n\tprivate async drainLifecycle(): Promise<void> {\n\t\twhile (this.pendingLifecycle.size > 0) {\n\t\t\tawait Promise.allSettled([...this.pendingLifecycle]);\n\t\t}\n\t}\n\n\tregisterChannel(provider: ChannelProvider): void {\n\t\t// Stop a same-named provider being replaced so its listeners/sockets don't leak (Bug #17).\n\t\tconst existing = this.channels.get(provider.name);\n\t\tif (existing && existing !== provider) this.trackLifecycle(() => existing.stop());\n\t\tthis.channels.set(provider.name, provider);\n\t\tif (this.started) this.trackLifecycle(() => provider.start(this.inboundHandler));\n\t}\n\n\tregisterScheduler(provider: JobSchedulerProvider): void {\n\t\tconst existing = this.schedulers.get(provider.name);\n\t\tif (existing && existing !== provider) this.trackLifecycle(() => existing.stop());\n\t\tthis.schedulers.set(provider.name, provider);\n\t\tif (this.started) this.trackLifecycle(() => provider.start());\n\t}\n\n\tgetChannel(name: string): ChannelProvider | undefined {\n\t\treturn this.channels.get(name);\n\t}\n\n\tget channelCount(): number {\n\t\treturn this.channels.size;\n\t}\n\n\tget schedulerCount(): number {\n\t\treturn this.schedulers.size;\n\t}\n\n\t/** Start every registered provider; inbound channel messages are routed to `onInbound`. */\n\tasync start(onInbound: ChannelInboundHandler): Promise<void> {\n\t\tif (this.started) {\n\t\t\tawait this.drainLifecycle();\n\t\t\treturn;\n\t\t}\n\t\tthis.started = true;\n\t\tthis.inboundHandler = onInbound;\n\t\tfor (const channel of this.channels.values()) {\n\t\t\ttry {\n\t\t\t\tawait channel.start(onInbound);\n\t\t\t} catch {\n\t\t\t\t// a failing channel must not block the others\n\t\t\t}\n\t\t}\n\t\tfor (const scheduler of this.schedulers.values()) {\n\t\t\ttry {\n\t\t\t\tawait scheduler.start();\n\t\t\t} catch {}\n\t\t}\n\t\tawait this.drainLifecycle();\n\t}\n\n\t/** Stop every registered provider. Best-effort; always leaves the registry stopped. */\n\tasync stop(): Promise<void> {\n\t\tif (!this.started) {\n\t\t\tawait this.drainLifecycle();\n\t\t\treturn;\n\t\t}\n\t\tthis.started = false;\n\t\t// Late-registration starts and replacement stops must settle before the final stop pass;\n\t\t// otherwise an async start can complete after shutdown and leak a listener/process.\n\t\tawait this.drainLifecycle();\n\t\tfor (const channel of this.channels.values()) {\n\t\t\ttry {\n\t\t\t\tawait channel.stop();\n\t\t\t} catch {}\n\t\t}\n\t\tfor (const scheduler of this.schedulers.values()) {\n\t\t\ttry {\n\t\t\t\tawait scheduler.stop();\n\t\t\t} catch {}\n\t\t}\n\t}\n}\n"]}

package/dist/core/gateways/channel-provider.js

@@ -17,22 +17,39 @@ export class GatewayRegistry {
     schedulers = new Map();
     started = false;
     inboundHandler = () => { };
+    pendingLifecycle = new Set();
+    trackLifecycle(operation) {
+        let pending;
+        try {
+            pending = Promise.resolve(operation()).catch(() => { });
+        }
+        catch {
+            return;
+        }
+        this.pendingLifecycle.add(pending);
+        void pending.finally(() => this.pendingLifecycle.delete(pending));
+    }
+    async drainLifecycle() {
+        while (this.pendingLifecycle.size > 0) {
+            await Promise.allSettled([...this.pendingLifecycle]);
+        }
+    }
     registerChannel(provider) {
         // Stop a same-named provider being replaced so its listeners/sockets don't leak (Bug #17).
         const existing = this.channels.get(provider.name);
         if (existing && existing !== provider)
-            void Promise.resolve(existing.stop()).catch(() => { });
+            this.trackLifecycle(() => existing.stop());
         this.channels.set(provider.name, provider);
         if (this.started)
-            void Promise.resolve(provider.start(this.inboundHandler)).catch(() => { });
+            this.trackLifecycle(() => provider.start(this.inboundHandler));
     }
     registerScheduler(provider) {
         const existing = this.schedulers.get(provider.name);
         if (existing && existing !== provider)
-            void Promise.resolve(existing.stop()).catch(() => { });
+            this.trackLifecycle(() => existing.stop());
         this.schedulers.set(provider.name, provider);
         if (this.started)
-            void Promise.resolve(provider.start()).catch(() => { });
+            this.trackLifecycle(() => provider.start());
     }
     getChannel(name) {
         return this.channels.get(name);
@@ -45,8 +62,10 @@ export class GatewayRegistry {
     }
     /** Start every registered provider; inbound channel messages are routed to `onInbound`. */
     async start(onInbound) {
-        if (this.started)
+        if (this.started) {
+            await this.drainLifecycle();
             return;
+        }
         this.started = true;
         this.inboundHandler = onInbound;
         for (const channel of this.channels.values()) {
@@ -63,12 +82,18 @@ export class GatewayRegistry {
             }
             catch { }
         }
+        await this.drainLifecycle();
     }
     /** Stop every registered provider. Best-effort; always leaves the registry stopped. */
     async stop() {
-        if (!this.started)
+        if (!this.started) {
+            await this.drainLifecycle();
             return;
+        }
         this.started = false;
+        // Late-registration starts and replacement stops must settle before the final stop pass;
+        // otherwise an async start can complete after shutdown and leak a listener/process.
+        await this.drainLifecycle();
         for (const channel of this.channels.values()) {
             try {
                 await channel.stop();

package/dist/core/gateways/channel-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"channel-provider.js","sourceRoot":"","sources":["../../../src/core/gateways/channel-provider.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Interface-driven gateways & scheduling (adaptive-agent design R8).\n *\n * pi does NOT bake transports (Slack/Discord/email/webhooks) or a cron tick loop into the core — that\n * would bloat the agent and couple it to deployment concerns. Instead it exposes two provider contracts\n * that a deployment wrapper (server, headless runner) implements and registers; the core only manages\n * their lifecycle. This keeps the CLI/agent transport- and schedule-agnostic while still offering a\n * first-class, uniform extension point.\n */\n\n/** A message arriving from / sent to an external channel (gateway). */\nexport interface ChannelMessage {\n\t/** Stable conversation/session key for this channel (e.g. `slack_C123`). */\n\tconversationKey: string;\n\t/** Message text. */\n\ttext: string;\n\t/** Optional opaque metadata the provider round-trips. */\n\tmeta?: Record<string, unknown>;\n}\n\n/** Handler the core supplies to a channel for inbound messages. */\nexport type ChannelInboundHandler = (message: ChannelMessage) => void | Promise<void>;\n\n/**\n * A transport channel (Telegram/Slack/email/webhook/...). Implemented by a deployment wrapper and\n * registered via {@link GatewayRegistry}. The core starts it (handing it an inbound handler) and stops\n * it on shutdown; it never imports any transport SDK itself.\n */\nexport interface ChannelProvider {\n\treadonly name: string;\n\t/** Begin listening; deliver inbound messages to `onInbound`. */\n\tstart(onInbound: ChannelInboundHandler): void | Promise<void>;\n\t/** Send an outbound message on this channel. */\n\tsend(message: ChannelMessage): void | Promise<void>;\n\t/** Stop listening and release resources. */\n\tstop(): void | Promise<void>;\n}\n\n/** A scheduled job definition. */\nexport interface ScheduledJob {\n\tid: string;\n\t/** Cron expression or interval spec the provider understands. */\n\tschedule: string;\n\t/** Invoked when the job fires. */\n\trun: () => void | Promise<void>;\n}\n\n/**\n * A scheduler (cron-like). Implemented by a deployment wrapper and registered via\n * {@link GatewayRegistry}. The core registers jobs + starts/stops it; it owns no tick loop itself.\n */\nexport interface JobSchedulerProvider {\n\treadonly name: string;\n\tschedule(job: ScheduledJob): void;\n\tstart(): void | Promise<void>;\n\tstop(): void | Promise<void>;\n}\n\n/**\n * Holds registered channel + scheduler providers and drives their lifecycle. A session starts all\n * registered providers when it binds and stops them on dispose. Registration is additive and idempotent\n * by provider name (last registration wins).\n */\nexport class GatewayRegistry {\n\tprivate readonly channels = new Map<string, ChannelProvider>();\n\tprivate readonly schedulers = new Map<string, JobSchedulerProvider>();\n\tprivate started = false;\n\tprivate inboundHandler: ChannelInboundHandler = () => {};\n\n\tregisterChannel(provider: ChannelProvider): void {\n\t\t// Stop a same-named provider being replaced so its listeners/sockets don't leak (Bug #17).\n\t\tconst existing = this.channels.get(provider.name);\n\t\tif (existing && existing !== provider) void Promise.resolve(existing.stop()).catch(() => {});\n\t\tthis.channels.set(provider.name, provider);\n\t\tif (this.started) void Promise.resolve(provider.start(this.inboundHandler)).catch(() => {});\n\t}\n\n\tregisterScheduler(provider: JobSchedulerProvider): void {\n\t\tconst existing = this.schedulers.get(provider.name);\n\t\tif (existing && existing !== provider) void Promise.resolve(existing.stop()).catch(() => {});\n\t\tthis.schedulers.set(provider.name, provider);\n\t\tif (this.started) void Promise.resolve(provider.start()).catch(() => {});\n\t}\n\n\tgetChannel(name: string): ChannelProvider | undefined {\n\t\treturn this.channels.get(name);\n\t}\n\n\tget channelCount(): number {\n\t\treturn this.channels.size;\n\t}\n\n\tget schedulerCount(): number {\n\t\treturn this.schedulers.size;\n\t}\n\n\t/** Start every registered provider; inbound channel messages are routed to `onInbound`. */\n\tasync start(onInbound: ChannelInboundHandler): Promise<void> {\n\t\tif (this.started) return;\n\t\tthis.started = true;\n\t\tthis.inboundHandler = onInbound;\n\t\tfor (const channel of this.channels.values()) {\n\t\t\ttry {\n\t\t\t\tawait channel.start(onInbound);\n\t\t\t} catch {\n\t\t\t\t// a failing channel must not block the others\n\t\t\t}\n\t\t}\n\t\tfor (const scheduler of this.schedulers.values()) {\n\t\t\ttry {\n\t\t\t\tawait scheduler.start();\n\t\t\t} catch {}\n\t\t}\n\t}\n\n\t/** Stop every registered provider. Best-effort; always leaves the registry stopped. */\n\tasync stop(): Promise<void> {\n\t\tif (!this.started) return;\n\t\tthis.started = false;\n\t\tfor (const channel of this.channels.values()) {\n\t\t\ttry {\n\t\t\t\tawait channel.stop();\n\t\t\t} catch {}\n\t\t}\n\t\tfor (const scheduler of this.schedulers.values()) {\n\t\t\ttry {\n\t\t\t\tawait scheduler.stop();\n\t\t\t} catch {}\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"channel-provider.js","sourceRoot":"","sources":["../../../src/core/gateways/channel-provider.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Interface-driven gateways & scheduling (adaptive-agent design R8).\n *\n * pi does NOT bake transports (Slack/Discord/email/webhooks) or a cron tick loop into the core — that\n * would bloat the agent and couple it to deployment concerns. Instead it exposes two provider contracts\n * that a deployment wrapper (server, headless runner) implements and registers; the core only manages\n * their lifecycle. This keeps the CLI/agent transport- and schedule-agnostic while still offering a\n * first-class, uniform extension point.\n */\n\n/** A message arriving from / sent to an external channel (gateway). */\nexport interface ChannelMessage {\n\t/** Stable conversation/session key for this channel (e.g. `slack_C123`). */\n\tconversationKey: string;\n\t/** Message text. */\n\ttext: string;\n\t/** Optional opaque metadata the provider round-trips. */\n\tmeta?: Record<string, unknown>;\n}\n\n/** Handler the core supplies to a channel for inbound messages. */\nexport type ChannelInboundHandler = (message: ChannelMessage) => void | Promise<void>;\n\n/**\n * A transport channel (Telegram/Slack/email/webhook/...). Implemented by a deployment wrapper and\n * registered via {@link GatewayRegistry}. The core starts it (handing it an inbound handler) and stops\n * it on shutdown; it never imports any transport SDK itself.\n */\nexport interface ChannelProvider {\n\treadonly name: string;\n\t/** Begin listening; deliver inbound messages to `onInbound`. */\n\tstart(onInbound: ChannelInboundHandler): void | Promise<void>;\n\t/** Send an outbound message on this channel. */\n\tsend(message: ChannelMessage): void | Promise<void>;\n\t/** Stop listening and release resources. */\n\tstop(): void | Promise<void>;\n}\n\n/** A scheduled job definition. */\nexport interface ScheduledJob {\n\tid: string;\n\t/** Cron expression or interval spec the provider understands. */\n\tschedule: string;\n\t/** Invoked when the job fires. */\n\trun: () => void | Promise<void>;\n}\n\n/**\n * A scheduler (cron-like). Implemented by a deployment wrapper and registered via\n * {@link GatewayRegistry}. The core registers jobs + starts/stops it; it owns no tick loop itself.\n */\nexport interface JobSchedulerProvider {\n\treadonly name: string;\n\tschedule(job: ScheduledJob): void;\n\tstart(): void | Promise<void>;\n\tstop(): void | Promise<void>;\n}\n\n/**\n * Holds registered channel + scheduler providers and drives their lifecycle. A session starts all\n * registered providers when it binds and stops them on dispose. Registration is additive and idempotent\n * by provider name (last registration wins).\n */\nexport class GatewayRegistry {\n\tprivate readonly channels = new Map<string, ChannelProvider>();\n\tprivate readonly schedulers = new Map<string, JobSchedulerProvider>();\n\tprivate started = false;\n\tprivate inboundHandler: ChannelInboundHandler = () => {};\n\tprivate readonly pendingLifecycle = new Set<Promise<void>>();\n\n\tprivate trackLifecycle(operation: () => void | Promise<void>): void {\n\t\tlet pending: Promise<void>;\n\t\ttry {\n\t\t\tpending = Promise.resolve(operation()).catch(() => {});\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t\tthis.pendingLifecycle.add(pending);\n\t\tvoid pending.finally(() => this.pendingLifecycle.delete(pending));\n\t}\n\n\tprivate async drainLifecycle(): Promise<void> {\n\t\twhile (this.pendingLifecycle.size > 0) {\n\t\t\tawait Promise.allSettled([...this.pendingLifecycle]);\n\t\t}\n\t}\n\n\tregisterChannel(provider: ChannelProvider): void {\n\t\t// Stop a same-named provider being replaced so its listeners/sockets don't leak (Bug #17).\n\t\tconst existing = this.channels.get(provider.name);\n\t\tif (existing && existing !== provider) this.trackLifecycle(() => existing.stop());\n\t\tthis.channels.set(provider.name, provider);\n\t\tif (this.started) this.trackLifecycle(() => provider.start(this.inboundHandler));\n\t}\n\n\tregisterScheduler(provider: JobSchedulerProvider): void {\n\t\tconst existing = this.schedulers.get(provider.name);\n\t\tif (existing && existing !== provider) this.trackLifecycle(() => existing.stop());\n\t\tthis.schedulers.set(provider.name, provider);\n\t\tif (this.started) this.trackLifecycle(() => provider.start());\n\t}\n\n\tgetChannel(name: string): ChannelProvider | undefined {\n\t\treturn this.channels.get(name);\n\t}\n\n\tget channelCount(): number {\n\t\treturn this.channels.size;\n\t}\n\n\tget schedulerCount(): number {\n\t\treturn this.schedulers.size;\n\t}\n\n\t/** Start every registered provider; inbound channel messages are routed to `onInbound`. */\n\tasync start(onInbound: ChannelInboundHandler): Promise<void> {\n\t\tif (this.started) {\n\t\t\tawait this.drainLifecycle();\n\t\t\treturn;\n\t\t}\n\t\tthis.started = true;\n\t\tthis.inboundHandler = onInbound;\n\t\tfor (const channel of this.channels.values()) {\n\t\t\ttry {\n\t\t\t\tawait channel.start(onInbound);\n\t\t\t} catch {\n\t\t\t\t// a failing channel must not block the others\n\t\t\t}\n\t\t}\n\t\tfor (const scheduler of this.schedulers.values()) {\n\t\t\ttry {\n\t\t\t\tawait scheduler.start();\n\t\t\t} catch {}\n\t\t}\n\t\tawait this.drainLifecycle();\n\t}\n\n\t/** Stop every registered provider. Best-effort; always leaves the registry stopped. */\n\tasync stop(): Promise<void> {\n\t\tif (!this.started) {\n\t\t\tawait this.drainLifecycle();\n\t\t\treturn;\n\t\t}\n\t\tthis.started = false;\n\t\t// Late-registration starts and replacement stops must settle before the final stop pass;\n\t\t// otherwise an async start can complete after shutdown and leak a listener/process.\n\t\tawait this.drainLifecycle();\n\t\tfor (const channel of this.channels.values()) {\n\t\t\ttry {\n\t\t\t\tawait channel.stop();\n\t\t\t} catch {}\n\t\t}\n\t\tfor (const scheduler of this.schedulers.values()) {\n\t\t\ttry {\n\t\t\t\tawait scheduler.stop();\n\t\t\t} catch {}\n\t\t}\n\t}\n}\n"]}

package/dist/core/goal-loop-controller.d.ts

@@ -5,7 +5,13 @@
  * active goal moving" loop: each pass reads the goal runtime snapshot, and — only while the snapshot
  * says `continue` — submits one continuation prompt back through the session's own prompt path. It
  * owns no state; the goal state lives in the session log and is read fresh every pass. Termination is
- * fully budget-gated (turn cap, wall-clock cap, and a no-progress guard on the goal-state key).
+ * fully budget-gated (per-invocation turn cap, per-invocation wall-clock cap, a DURABLE cumulative
+ * per-goal budget — turns + active wall-clock, persisted on `GoalState` across every invocation for
+ * the goal's lifetime — and a no-progress guard on a MEANINGFUL progress signature — satisfied-
+ * requirement count + ref-backed evidence count — so hollow goal-tool calls (e.g. add_requirement/
+ * reopen churn that satisfies nothing) cannot defeat the stall guard). Each submitted pass also
+ * reports its turn/wall-clock/spend contribution back to the session via `recordGoalContinuationPass`
+ * so the cumulative budget stays accurate.
  */
 import type { GoalContinuationLoopOptions, GoalContinuationLoopResult, GoalContinuationOnceOptions, GoalContinuationOnceResult, PromptOptions } from "./agent-session.ts";
 import type { GoalRuntimeSnapshot, GoalRuntimeSnapshotSettings } from "./goals/goal-runtime-snapshot.ts";
@@ -14,6 +20,16 @@ export interface GoalLoopControllerDeps {
     getGoalRuntimeSnapshot(settings: GoalRuntimeSnapshotSettings): GoalRuntimeSnapshot;
     /** Submit a continuation prompt through the session's own prompt path. */
     prompt(text: string, options?: PromptOptions): Promise<void>;
+    /**
+     * Persist one submitted pass's contribution to the active goal's durable cumulative budget
+     * (turns + active wall-clock; USD is attributed by the implementation from the session's own
+     * spend, not passed in here — see `AgentSession.recordGoalContinuationPass`). Called once per
+     * pass actually SUBMITTED (never for a no-op `continueGoalOnce` call).
+     */
+    recordGoalContinuationPass(pass: {
+        turns: number;
+        wallClockMs: number;
+    }): void;
 }
 export declare class GoalLoopController {
     private readonly deps;

package/dist/core/goal-loop-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"goal-loop-controller.d.ts","sourceRoot":"","sources":["../../src/core/goal-loop-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACX,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,aAAa,EACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAEzG,MAAM,WAAW,sBAAsB;IACtC,mGAAmG;IACnG,sBAAsB,CAAC,QAAQ,EAAE,2BAA2B,GAAG,mBAAmB,CAAC;IACnF,0EAA0E;IAC1E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAE9C,YAAY,IAAI,EAAE,sBAAsB,EAEvC;IAEK,gBAAgB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAehG;IAEK,gBAAgB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA+DhG;CACD","sourcesContent":["/**\n * Goal auto-continuation loop.\n *\n * Extracted verbatim from agent-session.ts (god-file decomposition). Drives the bounded \"keep the\n * active goal moving\" loop: each pass reads the goal runtime snapshot, and — only while the snapshot\n * says `continue` — submits one continuation prompt back through the session's own prompt path. It\n * owns no state; the goal state lives in the session log and is read fresh every pass. Termination is\n * fully budget-gated (turn cap, wall-clock cap, and a no-progress guard on the goal-state key).\n */\n\nimport type {\n\tGoalContinuationLoopOptions,\n\tGoalContinuationLoopResult,\n\tGoalContinuationOnceOptions,\n\tGoalContinuationOnceResult,\n\tPromptOptions,\n} from \"./agent-session.ts\";\nimport { buildGoalContinuationPrompt } from \"./goals/goal-continuation-prompt.ts\";\nimport type { GoalRuntimeSnapshot, GoalRuntimeSnapshotSettings } from \"./goals/goal-runtime-snapshot.ts\";\n\nexport interface GoalLoopControllerDeps {\n\t/** Read the current goal runtime snapshot (continuation decision + goal state) fresh each pass. */\n\tgetGoalRuntimeSnapshot(settings: GoalRuntimeSnapshotSettings): GoalRuntimeSnapshot;\n\t/** Submit a continuation prompt through the session's own prompt path. */\n\tprompt(text: string, options?: PromptOptions): Promise<void>;\n}\n\nexport class GoalLoopController {\n\tprivate readonly deps: GoalLoopControllerDeps;\n\n\tconstructor(deps: GoalLoopControllerDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\tasync continueGoalOnce(options: GoalContinuationOnceOptions): Promise<GoalContinuationOnceResult> {\n\t\tconst snapshot = this.deps.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });\n\n\t\tif (snapshot.continuation.action !== \"continue\") {\n\t\t\treturn { submitted: false, snapshot };\n\t\t}\n\n\t\tconst prompt = buildGoalContinuationPrompt({ snapshot, limits: options.promptLimits });\n\t\tawait this.deps.prompt(prompt.text, {\n\t\t\texpandPromptTemplates: false,\n\t\t\tprocessSlashCommands: false,\n\t\t\tautoContinueGoal: false,\n\t\t});\n\n\t\treturn { submitted: true, snapshot, prompt };\n\t}\n\n\tasync continueGoalLoop(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult> {\n\t\tlet turnsSubmitted = 0;\n\t\tconst now = options.now ?? Date.now;\n\t\tconst maxWallClockMs =\n\t\t\ttypeof options.maxWallClockMinutes === \"number\" && options.maxWallClockMinutes > 0\n\t\t\t\t? options.maxWallClockMinutes * 60_000\n\t\t\t\t: undefined;\n\t\tconst startedAt = now();\n\t\tconst hasReachedWallClockBudget = () => maxWallClockMs !== undefined && now() - startedAt >= maxWallClockMs;\n\t\tconst snapshot = () => this.deps.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });\n\n\t\tif (options.maxTurns <= 0) {\n\t\t\treturn {\n\t\t\t\tturnsSubmitted: 0,\n\t\t\t\tstopReason: \"max_turns_reached\",\n\t\t\t\tfinalSnapshot: snapshot(),\n\t\t\t};\n\t\t}\n\n\t\tif (hasReachedWallClockBudget()) {\n\t\t\treturn { turnsSubmitted, stopReason: \"wall_clock_budget_reached\", finalSnapshot: snapshot() };\n\t\t}\n\n\t\twhile (turnsSubmitted < options.maxTurns) {\n\t\t\tconst beforeSnapshot = snapshot();\n\t\t\tif (beforeSnapshot.continuation.action !== \"continue\") {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"continuation_not_allowed\", finalSnapshot: beforeSnapshot };\n\t\t\t}\n\n\t\t\tconst state = beforeSnapshot.goalState;\n\t\t\tconst beforeKey = state\n\t\t\t\t? `${state.goalId}:${state.updatedAt}:${state.events.length}:${state.stallTurns}:${state.status}`\n\t\t\t\t: undefined;\n\n\t\t\tconst result = await this.continueGoalOnce(options);\n\t\t\tif (result.submitted) {\n\t\t\t\tturnsSubmitted++;\n\t\t\t}\n\n\t\t\tif (hasReachedWallClockBudget()) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"wall_clock_budget_reached\", finalSnapshot: snapshot() };\n\t\t\t}\n\n\t\t\tconst afterSnapshot = snapshot();\n\t\t\tif (afterSnapshot.continuation.action !== \"continue\") {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"continuation_not_allowed\", finalSnapshot: afterSnapshot };\n\t\t\t}\n\n\t\t\tconst afterState = afterSnapshot.goalState;\n\t\t\tconst afterKey = afterState\n\t\t\t\t? `${afterState.goalId}:${afterState.updatedAt}:${afterState.events.length}:${afterState.stallTurns}:${afterState.status}`\n\t\t\t\t: undefined;\n\n\t\t\tif (beforeKey === afterKey) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"goal_state_not_advanced\", finalSnapshot: afterSnapshot };\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\tturnsSubmitted,\n\t\t\tstopReason: \"max_turns_reached\",\n\t\t\tfinalSnapshot: snapshot(),\n\t\t};\n\t}\n}\n"]}
+{"version":3,"file":"goal-loop-controller.d.ts","sourceRoot":"","sources":["../../src/core/goal-loop-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACX,2BAA2B,EAC3B,0BAA0B,EAE1B,2BAA2B,EAC3B,0BAA0B,EAC1B,aAAa,EACb,MAAM,oBAAoB,CAAC;AAO5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAiEzG,MAAM,WAAW,sBAAsB;IACtC,mGAAmG;IACnG,sBAAsB,CAAC,QAAQ,EAAE,2BAA2B,GAAG,mBAAmB,CAAC;IACnF,0EAA0E;IAC1E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,0BAA0B,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/E;AAED,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAE9C,YAAY,IAAI,EAAE,sBAAsB,EAEvC;IAEK,gBAAgB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAehG;IAEK,gBAAgB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAkEhG;CACD","sourcesContent":["/**\n * Goal auto-continuation loop.\n *\n * Extracted verbatim from agent-session.ts (god-file decomposition). Drives the bounded \"keep the\n * active goal moving\" loop: each pass reads the goal runtime snapshot, and — only while the snapshot\n * says `continue` — submits one continuation prompt back through the session's own prompt path. It\n * owns no state; the goal state lives in the session log and is read fresh every pass. Termination is\n * fully budget-gated (per-invocation turn cap, per-invocation wall-clock cap, a DURABLE cumulative\n * per-goal budget — turns + active wall-clock, persisted on `GoalState` across every invocation for\n * the goal's lifetime — and a no-progress guard on a MEANINGFUL progress signature — satisfied-\n * requirement count + ref-backed evidence count — so hollow goal-tool calls (e.g. add_requirement/\n * reopen churn that satisfies nothing) cannot defeat the stall guard). Each submitted pass also\n * reports its turn/wall-clock/spend contribution back to the session via `recordGoalContinuationPass`\n * so the cumulative budget stays accurate.\n */\n\nimport type {\n\tGoalContinuationLoopOptions,\n\tGoalContinuationLoopResult,\n\tGoalContinuationLoopStopReason,\n\tGoalContinuationOnceOptions,\n\tGoalContinuationOnceResult,\n\tPromptOptions,\n} from \"./agent-session.ts\";\nimport {\n\tDEFAULT_GOAL_CUMULATIVE_MAX_TURNS,\n\tDEFAULT_GOAL_CUMULATIVE_MAX_WALL_CLOCK_MS,\n\tDEFAULT_GOAL_CUMULATIVE_MAX_WORKER_SPEND_USD,\n} from \"./goals/goal-continuation-defaults.ts\";\nimport { buildGoalContinuationPrompt } from \"./goals/goal-continuation-prompt.ts\";\nimport type { GoalRuntimeSnapshot, GoalRuntimeSnapshotSettings } from \"./goals/goal-runtime-snapshot.ts\";\nimport type { GoalState } from \"./goals/goal-state.ts\";\n\n/**\n * Progress signature for goal-loop stall detection. Keys ONLY on state that reflects actual\n * progress toward the goal — `goalId`, `status`, the count of satisfied requirements, and the\n * count of evidence entries that carry a ref (`uri`) AND are TRUSTED: either actually validated\n * (`verified === true`) or `kind === \"user\"` (a human-confirmed claim). Deliberately excludes\n * `events.length`, `updatedAt`, and `stallTurns`: those change on every goal-tool call (including\n * no-op churn like re-adding/reopening a requirement without satisfying anything), which let hollow\n * passes look like progress and defeat `goal_state_not_advanced`.\n *\n * `verified` is `undefined` both for evidence that hasn't been checked yet AND for evidence kinds\n * that carry no checkable ref at all (`\"user\"`/`\"finding\"`/`\"test\"` — see the doc comment on\n * `GoalEvidenceRef.verified` in `goal-state.ts`). Treating \"undefined\" as trusted would let a model spam\n * `kind:\"finding\"` evidence with a fabricated `uri` every turn — always undefined, always counted —\n * which is the same class of hollow churn this signature exists to stop. So `undefined` does NOT\n * count; only an explicit `verified === true` (a real, checked ref) or `kind === \"user\"` (mirrors\n * the `complete` gate's trusted set in `goal-tool-core.ts`'s `isVerifiedOrUserEvidence`) counts.\n * `satisfiedRequirementCount` still advances the signature for legitimate-but-unverifiable work\n * (e.g. `kind:\"finding\"`/`\"test\"` evidence cited on a `satisfy_requirement` call), and the\n * continuation controller's own `stallTurns` path remains available for the model to self-report.\n */\nfunction goalProgressSignature(state: GoalState | undefined): string | undefined {\n\tif (!state) return undefined;\n\tconst satisfiedRequirementCount = state.requirements.filter(\n\t\t(requirement) => requirement.status === \"satisfied\",\n\t).length;\n\tconst refEvidenceCount = state.evidence.filter(\n\t\t(evidence) =>\n\t\t\ttypeof evidence.uri === \"string\" &&\n\t\t\tevidence.uri.trim().length > 0 &&\n\t\t\t(evidence.verified === true || evidence.kind === \"user\"),\n\t).length;\n\treturn `${state.goalId}:${state.status}:${satisfiedRequirementCount}:${refEvidenceCount}`;\n}\n\n/**\n * Whether the goal's DURABLE cumulative continuation budget (turns and/or active wall-clock,\n * persisted on `GoalState` and summed across every `continueGoalLoop` invocation for the goal's\n * lifetime) has been exhausted. Read fresh at the top of every pass (not just the top of the\n * invocation), so a single long-running invocation that crosses the ceiling mid-loop stops\n * immediately rather than waiting for the next invocation to notice. `undefined` counters (goal\n * state predating this field, or a fresh goal) count as `0` — never exhausted.\n */\nfunction isGoalContinuationBudgetExhausted(state: GoalState | undefined): boolean {\n\tif (!state) return false;\n\tif ((state.continuationTurnsUsed ?? 0) >= DEFAULT_GOAL_CUMULATIVE_MAX_TURNS) return true;\n\tif ((state.continuationWallClockMs ?? 0) >= DEFAULT_GOAL_CUMULATIVE_MAX_WALL_CLOCK_MS) return true;\n\tif ((state.continuationWorkerSpendUsd ?? 0) >= DEFAULT_GOAL_CUMULATIVE_MAX_WORKER_SPEND_USD) return true;\n\treturn false;\n}\n\n/**\n * Maps a non-\"continue\" continuation action onto the loop's own stopReason vocabulary.\n * `\"waiting\"` (a worker is dispatched against an open requirement) gets its OWN benign stopReason so\n * a wait is never misreported as `continuation_not_allowed` (which reads as a terminal refusal) —\n * callers/telemetry can tell \"paused, will resume on its own\" apart from \"stopped, needs a human or a\n * new decision.\" Every other non-continue action (ask-user/finalize/stop) keeps the existing\n * `continuation_not_allowed` stopReason unchanged.\n */\nfunction nonContinueStopReason(snapshot: GoalRuntimeSnapshot): GoalContinuationLoopStopReason {\n\treturn snapshot.continuation.action === \"waiting\" ? \"worker_in_flight\" : \"continuation_not_allowed\";\n}\n\nexport interface GoalLoopControllerDeps {\n\t/** Read the current goal runtime snapshot (continuation decision + goal state) fresh each pass. */\n\tgetGoalRuntimeSnapshot(settings: GoalRuntimeSnapshotSettings): GoalRuntimeSnapshot;\n\t/** Submit a continuation prompt through the session's own prompt path. */\n\tprompt(text: string, options?: PromptOptions): Promise<void>;\n\t/**\n\t * Persist one submitted pass's contribution to the active goal's durable cumulative budget\n\t * (turns + active wall-clock; USD is attributed by the implementation from the session's own\n\t * spend, not passed in here — see `AgentSession.recordGoalContinuationPass`). Called once per\n\t * pass actually SUBMITTED (never for a no-op `continueGoalOnce` call).\n\t */\n\trecordGoalContinuationPass(pass: { turns: number; wallClockMs: number }): void;\n}\n\nexport class GoalLoopController {\n\tprivate readonly deps: GoalLoopControllerDeps;\n\n\tconstructor(deps: GoalLoopControllerDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\tasync continueGoalOnce(options: GoalContinuationOnceOptions): Promise<GoalContinuationOnceResult> {\n\t\tconst snapshot = this.deps.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });\n\n\t\tif (snapshot.continuation.action !== \"continue\") {\n\t\t\treturn { submitted: false, snapshot };\n\t\t}\n\n\t\tconst prompt = buildGoalContinuationPrompt({ snapshot, limits: options.promptLimits });\n\t\tawait this.deps.prompt(prompt.text, {\n\t\t\texpandPromptTemplates: false,\n\t\t\tprocessSlashCommands: false,\n\t\t\tautoContinueGoal: false,\n\t\t});\n\n\t\treturn { submitted: true, snapshot, prompt };\n\t}\n\n\tasync continueGoalLoop(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult> {\n\t\tlet turnsSubmitted = 0;\n\t\tconst now = options.now ?? Date.now;\n\t\tconst maxWallClockMs =\n\t\t\ttypeof options.maxWallClockMinutes === \"number\" && options.maxWallClockMinutes > 0\n\t\t\t\t? options.maxWallClockMinutes * 60_000\n\t\t\t\t: undefined;\n\t\tconst startedAt = now();\n\t\tconst hasReachedWallClockBudget = () => maxWallClockMs !== undefined && now() - startedAt >= maxWallClockMs;\n\t\tconst snapshot = () => this.deps.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });\n\n\t\tif (options.maxTurns <= 0) {\n\t\t\treturn {\n\t\t\t\tturnsSubmitted: 0,\n\t\t\t\tstopReason: \"max_turns_reached\",\n\t\t\t\tfinalSnapshot: snapshot(),\n\t\t\t};\n\t\t}\n\n\t\tif (hasReachedWallClockBudget()) {\n\t\t\treturn { turnsSubmitted, stopReason: \"wall_clock_budget_reached\", finalSnapshot: snapshot() };\n\t\t}\n\n\t\twhile (turnsSubmitted < options.maxTurns) {\n\t\t\tconst beforeSnapshot = snapshot();\n\t\t\tif (beforeSnapshot.continuation.action !== \"continue\") {\n\t\t\t\treturn { turnsSubmitted, stopReason: nonContinueStopReason(beforeSnapshot), finalSnapshot: beforeSnapshot };\n\t\t\t}\n\n\t\t\t// Cumulative (durable, cross-invocation) budget — read fresh every pass, not just at the top\n\t\t\t// of this invocation, so a single long-running call still stops the moment it crosses the\n\t\t\t// ceiling rather than overshooting until the next invocation notices.\n\t\t\tif (isGoalContinuationBudgetExhausted(beforeSnapshot.goalState)) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"goal_budget_exhausted\", finalSnapshot: beforeSnapshot };\n\t\t\t}\n\n\t\t\tconst beforeKey = goalProgressSignature(beforeSnapshot.goalState);\n\n\t\t\tconst passStartedAt = now();\n\t\t\tconst result = await this.continueGoalOnce(options);\n\t\t\tif (result.submitted) {\n\t\t\t\tturnsSubmitted++;\n\t\t\t\tthis.deps.recordGoalContinuationPass({ turns: 1, wallClockMs: now() - passStartedAt });\n\t\t\t}\n\n\t\t\tif (hasReachedWallClockBudget()) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"wall_clock_budget_reached\", finalSnapshot: snapshot() };\n\t\t\t}\n\n\t\t\tconst afterSnapshot = snapshot();\n\t\t\tif (afterSnapshot.continuation.action !== \"continue\") {\n\t\t\t\treturn { turnsSubmitted, stopReason: nonContinueStopReason(afterSnapshot), finalSnapshot: afterSnapshot };\n\t\t\t}\n\n\t\t\tconst afterKey = goalProgressSignature(afterSnapshot.goalState);\n\n\t\t\tif (beforeKey === afterKey) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"goal_state_not_advanced\", finalSnapshot: afterSnapshot };\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\tturnsSubmitted,\n\t\t\tstopReason: \"max_turns_reached\",\n\t\t\tfinalSnapshot: snapshot(),\n\t\t};\n\t}\n}\n"]}

package/dist/core/goal-loop-controller.js

@@ -5,9 +5,75 @@
  * active goal moving" loop: each pass reads the goal runtime snapshot, and — only while the snapshot
  * says `continue` — submits one continuation prompt back through the session's own prompt path. It
  * owns no state; the goal state lives in the session log and is read fresh every pass. Termination is
- * fully budget-gated (turn cap, wall-clock cap, and a no-progress guard on the goal-state key).
+ * fully budget-gated (per-invocation turn cap, per-invocation wall-clock cap, a DURABLE cumulative
+ * per-goal budget — turns + active wall-clock, persisted on `GoalState` across every invocation for
+ * the goal's lifetime — and a no-progress guard on a MEANINGFUL progress signature — satisfied-
+ * requirement count + ref-backed evidence count — so hollow goal-tool calls (e.g. add_requirement/
+ * reopen churn that satisfies nothing) cannot defeat the stall guard). Each submitted pass also
+ * reports its turn/wall-clock/spend contribution back to the session via `recordGoalContinuationPass`
+ * so the cumulative budget stays accurate.
  */
+import { DEFAULT_GOAL_CUMULATIVE_MAX_TURNS, DEFAULT_GOAL_CUMULATIVE_MAX_WALL_CLOCK_MS, DEFAULT_GOAL_CUMULATIVE_MAX_WORKER_SPEND_USD, } from "./goals/goal-continuation-defaults.js";
 import { buildGoalContinuationPrompt } from "./goals/goal-continuation-prompt.js";
+/**
+ * Progress signature for goal-loop stall detection. Keys ONLY on state that reflects actual
+ * progress toward the goal — `goalId`, `status`, the count of satisfied requirements, and the
+ * count of evidence entries that carry a ref (`uri`) AND are TRUSTED: either actually validated
+ * (`verified === true`) or `kind === "user"` (a human-confirmed claim). Deliberately excludes
+ * `events.length`, `updatedAt`, and `stallTurns`: those change on every goal-tool call (including
+ * no-op churn like re-adding/reopening a requirement without satisfying anything), which let hollow
+ * passes look like progress and defeat `goal_state_not_advanced`.
+ *
+ * `verified` is `undefined` both for evidence that hasn't been checked yet AND for evidence kinds
+ * that carry no checkable ref at all (`"user"`/`"finding"`/`"test"` — see the doc comment on
+ * `GoalEvidenceRef.verified` in `goal-state.ts`). Treating "undefined" as trusted would let a model spam
+ * `kind:"finding"` evidence with a fabricated `uri` every turn — always undefined, always counted —
+ * which is the same class of hollow churn this signature exists to stop. So `undefined` does NOT
+ * count; only an explicit `verified === true` (a real, checked ref) or `kind === "user"` (mirrors
+ * the `complete` gate's trusted set in `goal-tool-core.ts`'s `isVerifiedOrUserEvidence`) counts.
+ * `satisfiedRequirementCount` still advances the signature for legitimate-but-unverifiable work
+ * (e.g. `kind:"finding"`/`"test"` evidence cited on a `satisfy_requirement` call), and the
+ * continuation controller's own `stallTurns` path remains available for the model to self-report.
+ */
+function goalProgressSignature(state) {
+    if (!state)
+        return undefined;
+    const satisfiedRequirementCount = state.requirements.filter((requirement) => requirement.status === "satisfied").length;
+    const refEvidenceCount = state.evidence.filter((evidence) => typeof evidence.uri === "string" &&
+        evidence.uri.trim().length > 0 &&
+        (evidence.verified === true || evidence.kind === "user")).length;
+    return `${state.goalId}:${state.status}:${satisfiedRequirementCount}:${refEvidenceCount}`;
+}
+/**
+ * Whether the goal's DURABLE cumulative continuation budget (turns and/or active wall-clock,
+ * persisted on `GoalState` and summed across every `continueGoalLoop` invocation for the goal's
+ * lifetime) has been exhausted. Read fresh at the top of every pass (not just the top of the
+ * invocation), so a single long-running invocation that crosses the ceiling mid-loop stops
+ * immediately rather than waiting for the next invocation to notice. `undefined` counters (goal
+ * state predating this field, or a fresh goal) count as `0` — never exhausted.
+ */
+function isGoalContinuationBudgetExhausted(state) {
+    if (!state)
+        return false;
+    if ((state.continuationTurnsUsed ?? 0) >= DEFAULT_GOAL_CUMULATIVE_MAX_TURNS)
+        return true;
+    if ((state.continuationWallClockMs ?? 0) >= DEFAULT_GOAL_CUMULATIVE_MAX_WALL_CLOCK_MS)
+        return true;
+    if ((state.continuationWorkerSpendUsd ?? 0) >= DEFAULT_GOAL_CUMULATIVE_MAX_WORKER_SPEND_USD)
+        return true;
+    return false;
+}
+/**
+ * Maps a non-"continue" continuation action onto the loop's own stopReason vocabulary.
+ * `"waiting"` (a worker is dispatched against an open requirement) gets its OWN benign stopReason so
+ * a wait is never misreported as `continuation_not_allowed` (which reads as a terminal refusal) —
+ * callers/telemetry can tell "paused, will resume on its own" apart from "stopped, needs a human or a
+ * new decision." Every other non-continue action (ask-user/finalize/stop) keeps the existing
+ * `continuation_not_allowed` stopReason unchanged.
+ */
+function nonContinueStopReason(snapshot) {
+    return snapshot.continuation.action === "waiting" ? "worker_in_flight" : "continuation_not_allowed";
+}
 export class GoalLoopController {
     deps;
     constructor(deps) {
@@ -48,27 +114,29 @@ export class GoalLoopController {
         while (turnsSubmitted < options.maxTurns) {
             const beforeSnapshot = snapshot();
             if (beforeSnapshot.continuation.action !== "continue") {
-                return { turnsSubmitted, stopReason: "continuation_not_allowed", finalSnapshot: beforeSnapshot };
+                return { turnsSubmitted, stopReason: nonContinueStopReason(beforeSnapshot), finalSnapshot: beforeSnapshot };
+            }
+            // Cumulative (durable, cross-invocation) budget — read fresh every pass, not just at the top
+            // of this invocation, so a single long-running call still stops the moment it crosses the
+            // ceiling rather than overshooting until the next invocation notices.
+            if (isGoalContinuationBudgetExhausted(beforeSnapshot.goalState)) {
+                return { turnsSubmitted, stopReason: "goal_budget_exhausted", finalSnapshot: beforeSnapshot };
             }
-            const state = beforeSnapshot.goalState;
-            const beforeKey = state
-                ? `${state.goalId}:${state.updatedAt}:${state.events.length}:${state.stallTurns}:${state.status}`
-                : undefined;
+            const beforeKey = goalProgressSignature(beforeSnapshot.goalState);
+            const passStartedAt = now();
             const result = await this.continueGoalOnce(options);
             if (result.submitted) {
                 turnsSubmitted++;
+                this.deps.recordGoalContinuationPass({ turns: 1, wallClockMs: now() - passStartedAt });
             }
             if (hasReachedWallClockBudget()) {
                 return { turnsSubmitted, stopReason: "wall_clock_budget_reached", finalSnapshot: snapshot() };
             }
             const afterSnapshot = snapshot();
             if (afterSnapshot.continuation.action !== "continue") {
-                return { turnsSubmitted, stopReason: "continuation_not_allowed", finalSnapshot: afterSnapshot };
+                return { turnsSubmitted, stopReason: nonContinueStopReason(afterSnapshot), finalSnapshot: afterSnapshot };
             }
-            const afterState = afterSnapshot.goalState;
-            const afterKey = afterState
-                ? `${afterState.goalId}:${afterState.updatedAt}:${afterState.events.length}:${afterState.stallTurns}:${afterState.status}`
-                : undefined;
+            const afterKey = goalProgressSignature(afterSnapshot.goalState);
             if (beforeKey === afterKey) {
                 return { turnsSubmitted, stopReason: "goal_state_not_advanced", finalSnapshot: afterSnapshot };
             }

package/dist/core/goal-loop-controller.js.map

@@ -1 +1 @@
-{"version":3,"file":"goal-loop-controller.js","sourceRoot":"","sources":["../../src/core/goal-loop-controller.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Goal auto-continuation loop.\n *\n * Extracted verbatim from agent-session.ts (god-file decomposition). Drives the bounded \"keep the\n * active goal moving\" loop: each pass reads the goal runtime snapshot, and — only while the snapshot\n * says `continue` — submits one continuation prompt back through the session's own prompt path. It\n * owns no state; the goal state lives in the session log and is read fresh every pass. Termination is\n * fully budget-gated (turn cap, wall-clock cap, and a no-progress guard on the goal-state key).\n */\n\nimport type {\n\tGoalContinuationLoopOptions,\n\tGoalContinuationLoopResult,\n\tGoalContinuationOnceOptions,\n\tGoalContinuationOnceResult,\n\tPromptOptions,\n} from \"./agent-session.ts\";\nimport { buildGoalContinuationPrompt } from \"./goals/goal-continuation-prompt.ts\";\nimport type { GoalRuntimeSnapshot, GoalRuntimeSnapshotSettings } from \"./goals/goal-runtime-snapshot.ts\";\n\nexport interface GoalLoopControllerDeps {\n\t/** Read the current goal runtime snapshot (continuation decision + goal state) fresh each pass. */\n\tgetGoalRuntimeSnapshot(settings: GoalRuntimeSnapshotSettings): GoalRuntimeSnapshot;\n\t/** Submit a continuation prompt through the session's own prompt path. */\n\tprompt(text: string, options?: PromptOptions): Promise<void>;\n}\n\nexport class GoalLoopController {\n\tprivate readonly deps: GoalLoopControllerDeps;\n\n\tconstructor(deps: GoalLoopControllerDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\tasync continueGoalOnce(options: GoalContinuationOnceOptions): Promise<GoalContinuationOnceResult> {\n\t\tconst snapshot = this.deps.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });\n\n\t\tif (snapshot.continuation.action !== \"continue\") {\n\t\t\treturn { submitted: false, snapshot };\n\t\t}\n\n\t\tconst prompt = buildGoalContinuationPrompt({ snapshot, limits: options.promptLimits });\n\t\tawait this.deps.prompt(prompt.text, {\n\t\t\texpandPromptTemplates: false,\n\t\t\tprocessSlashCommands: false,\n\t\t\tautoContinueGoal: false,\n\t\t});\n\n\t\treturn { submitted: true, snapshot, prompt };\n\t}\n\n\tasync continueGoalLoop(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult> {\n\t\tlet turnsSubmitted = 0;\n\t\tconst now = options.now ?? Date.now;\n\t\tconst maxWallClockMs =\n\t\t\ttypeof options.maxWallClockMinutes === \"number\" && options.maxWallClockMinutes > 0\n\t\t\t\t? options.maxWallClockMinutes * 60_000\n\t\t\t\t: undefined;\n\t\tconst startedAt = now();\n\t\tconst hasReachedWallClockBudget = () => maxWallClockMs !== undefined && now() - startedAt >= maxWallClockMs;\n\t\tconst snapshot = () => this.deps.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });\n\n\t\tif (options.maxTurns <= 0) {\n\t\t\treturn {\n\t\t\t\tturnsSubmitted: 0,\n\t\t\t\tstopReason: \"max_turns_reached\",\n\t\t\t\tfinalSnapshot: snapshot(),\n\t\t\t};\n\t\t}\n\n\t\tif (hasReachedWallClockBudget()) {\n\t\t\treturn { turnsSubmitted, stopReason: \"wall_clock_budget_reached\", finalSnapshot: snapshot() };\n\t\t}\n\n\t\twhile (turnsSubmitted < options.maxTurns) {\n\t\t\tconst beforeSnapshot = snapshot();\n\t\t\tif (beforeSnapshot.continuation.action !== \"continue\") {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"continuation_not_allowed\", finalSnapshot: beforeSnapshot };\n\t\t\t}\n\n\t\t\tconst state = beforeSnapshot.goalState;\n\t\t\tconst beforeKey = state\n\t\t\t\t? `${state.goalId}:${state.updatedAt}:${state.events.length}:${state.stallTurns}:${state.status}`\n\t\t\t\t: undefined;\n\n\t\t\tconst result = await this.continueGoalOnce(options);\n\t\t\tif (result.submitted) {\n\t\t\t\tturnsSubmitted++;\n\t\t\t}\n\n\t\t\tif (hasReachedWallClockBudget()) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"wall_clock_budget_reached\", finalSnapshot: snapshot() };\n\t\t\t}\n\n\t\t\tconst afterSnapshot = snapshot();\n\t\t\tif (afterSnapshot.continuation.action !== \"continue\") {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"continuation_not_allowed\", finalSnapshot: afterSnapshot };\n\t\t\t}\n\n\t\t\tconst afterState = afterSnapshot.goalState;\n\t\t\tconst afterKey = afterState\n\t\t\t\t? `${afterState.goalId}:${afterState.updatedAt}:${afterState.events.length}:${afterState.stallTurns}:${afterState.status}`\n\t\t\t\t: undefined;\n\n\t\t\tif (beforeKey === afterKey) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"goal_state_not_advanced\", finalSnapshot: afterSnapshot };\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\tturnsSubmitted,\n\t\t\tstopReason: \"max_turns_reached\",\n\t\t\tfinalSnapshot: snapshot(),\n\t\t};\n\t}\n}\n"]}
+{"version":3,"file":"goal-loop-controller.js","sourceRoot":"","sources":["../../src/core/goal-loop-controller.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Goal auto-continuation loop.\n *\n * Extracted verbatim from agent-session.ts (god-file decomposition). Drives the bounded \"keep the\n * active goal moving\" loop: each pass reads the goal runtime snapshot, and — only while the snapshot\n * says `continue` — submits one continuation prompt back through the session's own prompt path. It\n * owns no state; the goal state lives in the session log and is read fresh every pass. Termination is\n * fully budget-gated (per-invocation turn cap, per-invocation wall-clock cap, a DURABLE cumulative\n * per-goal budget — turns + active wall-clock, persisted on `GoalState` across every invocation for\n * the goal's lifetime — and a no-progress guard on a MEANINGFUL progress signature — satisfied-\n * requirement count + ref-backed evidence count — so hollow goal-tool calls (e.g. add_requirement/\n * reopen churn that satisfies nothing) cannot defeat the stall guard). Each submitted pass also\n * reports its turn/wall-clock/spend contribution back to the session via `recordGoalContinuationPass`\n * so the cumulative budget stays accurate.\n */\n\nimport type {\n\tGoalContinuationLoopOptions,\n\tGoalContinuationLoopResult,\n\tGoalContinuationLoopStopReason,\n\tGoalContinuationOnceOptions,\n\tGoalContinuationOnceResult,\n\tPromptOptions,\n} from \"./agent-session.ts\";\nimport {\n\tDEFAULT_GOAL_CUMULATIVE_MAX_TURNS,\n\tDEFAULT_GOAL_CUMULATIVE_MAX_WALL_CLOCK_MS,\n\tDEFAULT_GOAL_CUMULATIVE_MAX_WORKER_SPEND_USD,\n} from \"./goals/goal-continuation-defaults.ts\";\nimport { buildGoalContinuationPrompt } from \"./goals/goal-continuation-prompt.ts\";\nimport type { GoalRuntimeSnapshot, GoalRuntimeSnapshotSettings } from \"./goals/goal-runtime-snapshot.ts\";\nimport type { GoalState } from \"./goals/goal-state.ts\";\n\n/**\n * Progress signature for goal-loop stall detection. Keys ONLY on state that reflects actual\n * progress toward the goal — `goalId`, `status`, the count of satisfied requirements, and the\n * count of evidence entries that carry a ref (`uri`) AND are TRUSTED: either actually validated\n * (`verified === true`) or `kind === \"user\"` (a human-confirmed claim). Deliberately excludes\n * `events.length`, `updatedAt`, and `stallTurns`: those change on every goal-tool call (including\n * no-op churn like re-adding/reopening a requirement without satisfying anything), which let hollow\n * passes look like progress and defeat `goal_state_not_advanced`.\n *\n * `verified` is `undefined` both for evidence that hasn't been checked yet AND for evidence kinds\n * that carry no checkable ref at all (`\"user\"`/`\"finding\"`/`\"test\"` — see the doc comment on\n * `GoalEvidenceRef.verified` in `goal-state.ts`). Treating \"undefined\" as trusted would let a model spam\n * `kind:\"finding\"` evidence with a fabricated `uri` every turn — always undefined, always counted —\n * which is the same class of hollow churn this signature exists to stop. So `undefined` does NOT\n * count; only an explicit `verified === true` (a real, checked ref) or `kind === \"user\"` (mirrors\n * the `complete` gate's trusted set in `goal-tool-core.ts`'s `isVerifiedOrUserEvidence`) counts.\n * `satisfiedRequirementCount` still advances the signature for legitimate-but-unverifiable work\n * (e.g. `kind:\"finding\"`/`\"test\"` evidence cited on a `satisfy_requirement` call), and the\n * continuation controller's own `stallTurns` path remains available for the model to self-report.\n */\nfunction goalProgressSignature(state: GoalState | undefined): string | undefined {\n\tif (!state) return undefined;\n\tconst satisfiedRequirementCount = state.requirements.filter(\n\t\t(requirement) => requirement.status === \"satisfied\",\n\t).length;\n\tconst refEvidenceCount = state.evidence.filter(\n\t\t(evidence) =>\n\t\t\ttypeof evidence.uri === \"string\" &&\n\t\t\tevidence.uri.trim().length > 0 &&\n\t\t\t(evidence.verified === true || evidence.kind === \"user\"),\n\t).length;\n\treturn `${state.goalId}:${state.status}:${satisfiedRequirementCount}:${refEvidenceCount}`;\n}\n\n/**\n * Whether the goal's DURABLE cumulative continuation budget (turns and/or active wall-clock,\n * persisted on `GoalState` and summed across every `continueGoalLoop` invocation for the goal's\n * lifetime) has been exhausted. Read fresh at the top of every pass (not just the top of the\n * invocation), so a single long-running invocation that crosses the ceiling mid-loop stops\n * immediately rather than waiting for the next invocation to notice. `undefined` counters (goal\n * state predating this field, or a fresh goal) count as `0` — never exhausted.\n */\nfunction isGoalContinuationBudgetExhausted(state: GoalState | undefined): boolean {\n\tif (!state) return false;\n\tif ((state.continuationTurnsUsed ?? 0) >= DEFAULT_GOAL_CUMULATIVE_MAX_TURNS) return true;\n\tif ((state.continuationWallClockMs ?? 0) >= DEFAULT_GOAL_CUMULATIVE_MAX_WALL_CLOCK_MS) return true;\n\tif ((state.continuationWorkerSpendUsd ?? 0) >= DEFAULT_GOAL_CUMULATIVE_MAX_WORKER_SPEND_USD) return true;\n\treturn false;\n}\n\n/**\n * Maps a non-\"continue\" continuation action onto the loop's own stopReason vocabulary.\n * `\"waiting\"` (a worker is dispatched against an open requirement) gets its OWN benign stopReason so\n * a wait is never misreported as `continuation_not_allowed` (which reads as a terminal refusal) —\n * callers/telemetry can tell \"paused, will resume on its own\" apart from \"stopped, needs a human or a\n * new decision.\" Every other non-continue action (ask-user/finalize/stop) keeps the existing\n * `continuation_not_allowed` stopReason unchanged.\n */\nfunction nonContinueStopReason(snapshot: GoalRuntimeSnapshot): GoalContinuationLoopStopReason {\n\treturn snapshot.continuation.action === \"waiting\" ? \"worker_in_flight\" : \"continuation_not_allowed\";\n}\n\nexport interface GoalLoopControllerDeps {\n\t/** Read the current goal runtime snapshot (continuation decision + goal state) fresh each pass. */\n\tgetGoalRuntimeSnapshot(settings: GoalRuntimeSnapshotSettings): GoalRuntimeSnapshot;\n\t/** Submit a continuation prompt through the session's own prompt path. */\n\tprompt(text: string, options?: PromptOptions): Promise<void>;\n\t/**\n\t * Persist one submitted pass's contribution to the active goal's durable cumulative budget\n\t * (turns + active wall-clock; USD is attributed by the implementation from the session's own\n\t * spend, not passed in here — see `AgentSession.recordGoalContinuationPass`). Called once per\n\t * pass actually SUBMITTED (never for a no-op `continueGoalOnce` call).\n\t */\n\trecordGoalContinuationPass(pass: { turns: number; wallClockMs: number }): void;\n}\n\nexport class GoalLoopController {\n\tprivate readonly deps: GoalLoopControllerDeps;\n\n\tconstructor(deps: GoalLoopControllerDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\tasync continueGoalOnce(options: GoalContinuationOnceOptions): Promise<GoalContinuationOnceResult> {\n\t\tconst snapshot = this.deps.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });\n\n\t\tif (snapshot.continuation.action !== \"continue\") {\n\t\t\treturn { submitted: false, snapshot };\n\t\t}\n\n\t\tconst prompt = buildGoalContinuationPrompt({ snapshot, limits: options.promptLimits });\n\t\tawait this.deps.prompt(prompt.text, {\n\t\t\texpandPromptTemplates: false,\n\t\t\tprocessSlashCommands: false,\n\t\t\tautoContinueGoal: false,\n\t\t});\n\n\t\treturn { submitted: true, snapshot, prompt };\n\t}\n\n\tasync continueGoalLoop(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult> {\n\t\tlet turnsSubmitted = 0;\n\t\tconst now = options.now ?? Date.now;\n\t\tconst maxWallClockMs =\n\t\t\ttypeof options.maxWallClockMinutes === \"number\" && options.maxWallClockMinutes > 0\n\t\t\t\t? options.maxWallClockMinutes * 60_000\n\t\t\t\t: undefined;\n\t\tconst startedAt = now();\n\t\tconst hasReachedWallClockBudget = () => maxWallClockMs !== undefined && now() - startedAt >= maxWallClockMs;\n\t\tconst snapshot = () => this.deps.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });\n\n\t\tif (options.maxTurns <= 0) {\n\t\t\treturn {\n\t\t\t\tturnsSubmitted: 0,\n\t\t\t\tstopReason: \"max_turns_reached\",\n\t\t\t\tfinalSnapshot: snapshot(),\n\t\t\t};\n\t\t}\n\n\t\tif (hasReachedWallClockBudget()) {\n\t\t\treturn { turnsSubmitted, stopReason: \"wall_clock_budget_reached\", finalSnapshot: snapshot() };\n\t\t}\n\n\t\twhile (turnsSubmitted < options.maxTurns) {\n\t\t\tconst beforeSnapshot = snapshot();\n\t\t\tif (beforeSnapshot.continuation.action !== \"continue\") {\n\t\t\t\treturn { turnsSubmitted, stopReason: nonContinueStopReason(beforeSnapshot), finalSnapshot: beforeSnapshot };\n\t\t\t}\n\n\t\t\t// Cumulative (durable, cross-invocation) budget — read fresh every pass, not just at the top\n\t\t\t// of this invocation, so a single long-running call still stops the moment it crosses the\n\t\t\t// ceiling rather than overshooting until the next invocation notices.\n\t\t\tif (isGoalContinuationBudgetExhausted(beforeSnapshot.goalState)) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"goal_budget_exhausted\", finalSnapshot: beforeSnapshot };\n\t\t\t}\n\n\t\t\tconst beforeKey = goalProgressSignature(beforeSnapshot.goalState);\n\n\t\t\tconst passStartedAt = now();\n\t\t\tconst result = await this.continueGoalOnce(options);\n\t\t\tif (result.submitted) {\n\t\t\t\tturnsSubmitted++;\n\t\t\t\tthis.deps.recordGoalContinuationPass({ turns: 1, wallClockMs: now() - passStartedAt });\n\t\t\t}\n\n\t\t\tif (hasReachedWallClockBudget()) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"wall_clock_budget_reached\", finalSnapshot: snapshot() };\n\t\t\t}\n\n\t\t\tconst afterSnapshot = snapshot();\n\t\t\tif (afterSnapshot.continuation.action !== \"continue\") {\n\t\t\t\treturn { turnsSubmitted, stopReason: nonContinueStopReason(afterSnapshot), finalSnapshot: afterSnapshot };\n\t\t\t}\n\n\t\t\tconst afterKey = goalProgressSignature(afterSnapshot.goalState);\n\n\t\t\tif (beforeKey === afterKey) {\n\t\t\t\treturn { turnsSubmitted, stopReason: \"goal_state_not_advanced\", finalSnapshot: afterSnapshot };\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\tturnsSubmitted,\n\t\t\tstopReason: \"max_turns_reached\",\n\t\t\tfinalSnapshot: snapshot(),\n\t\t};\n\t}\n}\n"]}

package/dist/core/goals/goal-acceptance.d.ts

@@ -0,0 +1,11 @@
+import type { GoalEvidenceRef, GoalState, Requirement } from "./goal-state.ts";
+export declare function isTrustedGoalEvidence(evidence: GoalEvidenceRef): boolean;
+export declare function getTrustedRequirementEvidence(state: GoalState, requirement: Requirement): GoalEvidenceRef[];
+export declare function getUnprovenGoalRequirementIds(state: GoalState): string[];
+/**
+ * Human/manual completion and the explicit evidence-gate opt-out are authoritative overrides.
+ * Completion events written before the flag existed are treated as legacy owner decisions so an
+ * already-completed persisted goal cannot strand durable work during resume.
+ */
+export declare function hasGoalAcceptanceOverride(state: GoalState): boolean;
+//# sourceMappingURL=goal-acceptance.d.ts.map

package/dist/core/goals/goal-acceptance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-acceptance.d.ts","sourceRoot":"","sources":["../../../src/core/goals/goal-acceptance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE/E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAExE;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,GAAG,eAAe,EAAE,CAG3G;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAOxE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAQnE","sourcesContent":["import type { GoalEvidenceRef, GoalState, Requirement } from \"./goal-state.ts\";\n\nexport function isTrustedGoalEvidence(evidence: GoalEvidenceRef): boolean {\n\treturn evidence.kind === \"user\" || evidence.verified === true;\n}\n\nexport function getTrustedRequirementEvidence(state: GoalState, requirement: Requirement): GoalEvidenceRef[] {\n\tconst evidenceIds = new Set(requirement.evidenceIds);\n\treturn state.evidence.filter((evidence) => evidenceIds.has(evidence.id) && isTrustedGoalEvidence(evidence));\n}\n\nexport function getUnprovenGoalRequirementIds(state: GoalState): string[] {\n\treturn state.requirements\n\t\t.filter(\n\t\t\t(requirement) =>\n\t\t\t\trequirement.status !== \"satisfied\" || getTrustedRequirementEvidence(state, requirement).length === 0,\n\t\t)\n\t\t.map((requirement) => requirement.id);\n}\n\n/**\n * Human/manual completion and the explicit evidence-gate opt-out are authoritative overrides.\n * Completion events written before the flag existed are treated as legacy owner decisions so an\n * already-completed persisted goal cannot strand durable work during resume.\n */\nexport function hasGoalAcceptanceOverride(state: GoalState): boolean {\n\tconst completion = [...state.events]\n\t\t.reverse()\n\t\t.find((event) => event.type === \"complete_goal\" || event.type === \"complete_goal_manually\");\n\treturn (\n\t\tcompletion?.type === \"complete_goal_manually\" ||\n\t\t(completion?.type === \"complete_goal\" && completion.acceptanceOverride !== false)\n\t);\n}\n"]}