@caupulican/pi-adaptative 0.81.39 → 0.81.41

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,CAShD;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,CAoB3C;IAED,OAAO,CAAC,WAAW;IAMnB,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\tif (message.stopReason === \"aborted\") {\n\t\t\tthis.finishRetry(false, message.errorMessage ?? \"Retry aborted\");\n\t\t\treturn;\n\t\t}\n\t\tthis.deps.onSuccessfulAssistant();\n\t\tthis.finishRetry(true);\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.finishRetry(false, message.errorMessage);\n\t\tif (await this.deps.checkCompaction(message)) return true;\n\t\treturn this.deps.agent.hasQueuedMessages();\n\t}\n\n\tprivate finishRetry(success: boolean, finalError?: string): void {\n\t\tif (this.retry.attempt === 0) return;\n\t\tthis.deps.emit({ type: \"auto_retry_end\", success, attempt: this.retry.attempt, finalError });\n\t\tthis.retry.reset();\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;
+        if (message.stopReason === "aborted") {
+            this.finishRetry(false, message.errorMessage ?? "Retry aborted");
+            return;
+        }
+        this.deps.onSuccessfulAssistant();
+        this.finishRetry(true);
+    }
+    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.finishRetry(false, message.errorMessage);
+        if (await this.deps.checkCompaction(message))
+            return true;
+        return this.deps.agent.hasQueuedMessages();
+    }
+    finishRetry(success, finalError) {
+        if (this.retry.attempt === 0)
+            return;
+        this.deps.emit({ type: "auto_retry_end", success, attempt: this.retry.attempt, finalError });
+        this.retry.reset();
+    }
+    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\tif (message.stopReason === \"aborted\") {\n\t\t\tthis.finishRetry(false, message.errorMessage ?? \"Retry aborted\");\n\t\t\treturn;\n\t\t}\n\t\tthis.deps.onSuccessfulAssistant();\n\t\tthis.finishRetry(true);\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.finishRetry(false, message.errorMessage);\n\t\tif (await this.deps.checkCompaction(message)) return true;\n\t\treturn this.deps.agent.hasQueuedMessages();\n\t}\n\n\tprivate finishRetry(success: boolean, finalError?: string): void {\n\t\tif (this.retry.attempt === 0) return;\n\t\tthis.deps.emit({ type: \"auto_retry_end\", success, attempt: this.retry.attempt, finalError });\n\t\tthis.retry.reset();\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,23 +5,23 @@
  * 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 (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.
+ * gated only by real terminal conditions and limits the owner explicitly supplied: an optional
+ * per-invocation turn cap, an optional per-invocation wall-clock cap, and an optional durable token
+ * budget on the goal. Each submitted pass still reports exact token/wall-clock/spend contribution
+ * for observability. Progress is inferred from real work and terminal goal updates; telemetry never
+ * becomes an implicit execution limit.
  */
-import type { GoalContinuationLoopOptions, GoalContinuationLoopResult, GoalContinuationOnceOptions, GoalContinuationOnceResult, PromptOptions } from "./agent-session.ts";
+import type { GoalContinuationLoopOptions, GoalContinuationLoopResult, GoalContinuationOnceOptions, GoalContinuationOnceResult, PromptOptions } from "./agent-session-contracts.ts";
 import type { GoalRuntimeSnapshot, GoalRuntimeSnapshotSettings } from "./goals/goal-runtime-snapshot.ts";
 export interface GoalLoopControllerDeps {
     /** Read the current goal runtime snapshot (continuation decision + goal state) fresh each pass. */
     getGoalRuntimeSnapshot(settings: GoalRuntimeSnapshotSettings): GoalRuntimeSnapshot;
     /** Submit a continuation prompt through the session's own prompt path. */
     prompt(text: string, options?: PromptOptions): Promise<void>;
+    /** Capture the append-only branch cursor immediately before a continuation prompt. */
+    captureUsageCursor(): string | null;
     /**
-     * Persist one submitted pass's contribution to the active goal's durable cumulative budget
+     * Persist one submitted pass's contribution to the active goal's durable cumulative accounting
      * (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).
@@ -29,7 +29,12 @@ export interface GoalLoopControllerDeps {
     recordGoalContinuationPass(pass: {
         turns: number;
         wallClockMs: number;
+        usageCursor: string | null;
     }): void;
+    /** Persist an exhausted/non-retryable continuation failure as a stopped goal state. */
+    recordGoalContinuationFailure(error: unknown): void;
+    /** Persist a reason-specific budget terminal state before returning control. */
+    markGoalBudgetLimited(reason: string): 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;;;;;;;;;;;;;;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"]}
+{"version":3,"file":"goal-loop-controller.d.ts","sourceRoot":"","sources":["../../src/core/goal-loop-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACX,2BAA2B,EAC3B,0BAA0B,EAE1B,2BAA2B,EAC3B,0BAA0B,EAC1B,aAAa,EACb,MAAM,8BAA8B,CAAC;AAKtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AA4BzG,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,sFAAsF;IACtF,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAAC;IACpC;;;;;OAKG;IACH,0BAA0B,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3G,uFAAuF;IACvF,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACpD,gFAAgF;IAChF,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;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,CAgBhG;IAEK,gBAAgB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAsEhG;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 * gated only by real terminal conditions and limits the owner explicitly supplied: an optional\n * per-invocation turn cap, an optional per-invocation wall-clock cap, and an optional durable token\n * budget on the goal. Each submitted pass still reports exact token/wall-clock/spend contribution\n * for observability. Progress is inferred from real work and terminal goal updates; telemetry never\n * becomes an implicit execution limit.\n */\n\nimport type {\n\tGoalContinuationLoopOptions,\n\tGoalContinuationLoopResult,\n\tGoalContinuationLoopStopReason,\n\tGoalContinuationOnceOptions,\n\tGoalContinuationOnceResult,\n\tPromptOptions,\n} from \"./agent-session-contracts.ts\";\nimport {\n\tbuildGoalContinuationPrompt,\n\tGOAL_CONTINUATION_TRIGGER_CUSTOM_TYPE,\n} 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 * Resolve an owner-supplied durable goal budget. Wall-clock and spend counters are deliberately\n * absent here: they are telemetry unless the public goal contract grows matching explicit limits.\n * Execution limits are policy inputs, not hidden runtime defaults.\n */\nfunction getExplicitGoalBudgetExhaustion(state: GoalState | undefined): string | undefined {\n\tif (!state || state.status !== \"active\") return undefined;\n\tif (state.tokenBudget !== undefined && (state.tokensUsed ?? 0) >= state.tokenBudget) {\n\t\treturn `token budget exhausted (${state.tokensUsed ?? 0}/${state.tokenBudget})`;\n\t}\n\treturn undefined;\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/** Capture the append-only branch cursor immediately before a continuation prompt. */\n\tcaptureUsageCursor(): string | null;\n\t/**\n\t * Persist one submitted pass's contribution to the active goal's durable cumulative accounting\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; usageCursor: string | null }): void;\n\t/** Persist an exhausted/non-retryable continuation failure as a stopped goal state. */\n\trecordGoalContinuationFailure(error: unknown): void;\n\t/** Persist a reason-specific budget terminal state before returning control. */\n\tmarkGoalBudgetLimited(reason: string): 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();\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\tinternalContextType: GOAL_CONTINUATION_TRIGGER_CUSTOM_TYPE,\n\t\t});\n\n\t\treturn { submitted: true, snapshot, prompt };\n\t}\n\n\tasync continueGoalLoop(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult> {\n\t\tif (!Number.isSafeInteger(options.maxTurns) || options.maxTurns < 0) {\n\t\t\tthrow new Error(\"Goal continuation maxTurns must be a non-negative safe integer; 0 means unbounded.\");\n\t\t}\n\t\tlet turnsSubmitted = 0;\n\t\tconst hasExplicitTurnLimit = options.maxTurns > 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 (hasReachedWallClockBudget()) {\n\t\t\treturn { turnsSubmitted, stopReason: \"wall_clock_budget_reached\", finalSnapshot: snapshot() };\n\t\t}\n\n\t\twhile (!hasExplicitTurnLimit || 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// Owner-supplied durable token budget — read fresh every pass so an invocation stops as\n\t\t\t// soon as its own latest persisted usage crosses the explicit ceiling.\n\t\t\tconst beforeBudgetExhaustion = getExplicitGoalBudgetExhaustion(beforeSnapshot.goalState);\n\t\t\tif (beforeBudgetExhaustion) {\n\t\t\t\tthis.deps.markGoalBudgetLimited(beforeBudgetExhaustion);\n\t\t\t\treturn { turnsSubmitted, stopReason: \"goal_budget_exhausted\", finalSnapshot: snapshot() };\n\t\t\t}\n\n\t\t\tconst passStartedAt = now();\n\t\t\tconst usageCursor = this.deps.captureUsageCursor();\n\t\t\tlet result: GoalContinuationOnceResult;\n\t\t\ttry {\n\t\t\t\tresult = await this.continueGoalOnce(options);\n\t\t\t} catch (error) {\n\t\t\t\tturnsSubmitted++;\n\t\t\t\tthis.deps.recordGoalContinuationPass({ turns: 1, wallClockMs: now() - passStartedAt, usageCursor });\n\t\t\t\tthis.deps.recordGoalContinuationFailure(error);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (result.submitted) {\n\t\t\t\tturnsSubmitted++;\n\t\t\t\tthis.deps.recordGoalContinuationPass({ turns: 1, wallClockMs: now() - passStartedAt, usageCursor });\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\tlet afterSnapshot = snapshot();\n\t\t\tconst afterBudgetExhaustion = getExplicitGoalBudgetExhaustion(afterSnapshot.goalState);\n\t\t\tif (afterBudgetExhaustion) {\n\t\t\t\tthis.deps.markGoalBudgetLimited(afterBudgetExhaustion);\n\t\t\t\tafterSnapshot = snapshot();\n\t\t\t\treturn { turnsSubmitted, stopReason: \"goal_budget_exhausted\", finalSnapshot: afterSnapshot };\n\t\t\t}\n\t\t\tif (afterSnapshot.continuation.action !== \"continue\") {\n\t\t\t\treturn { turnsSubmitted, stopReason: nonContinueStopReason(afterSnapshot), 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,63 +5,25 @@
  * 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 (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.
+ * gated only by real terminal conditions and limits the owner explicitly supplied: an optional
+ * per-invocation turn cap, an optional per-invocation wall-clock cap, and an optional durable token
+ * budget on the goal. Each submitted pass still reports exact token/wall-clock/spend contribution
+ * for observability. Progress is inferred from real work and terminal goal updates; telemetry never
+ * becomes an implicit execution limit.
  */
-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";
+import { buildGoalContinuationPrompt, GOAL_CONTINUATION_TRIGGER_CUSTOM_TYPE, } 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.
+ * Resolve an owner-supplied durable goal budget. Wall-clock and spend counters are deliberately
+ * absent here: they are telemetry unless the public goal contract grows matching explicit limits.
+ * Execution limits are policy inputs, not hidden runtime defaults.
  */
-function goalProgressSignature(state) {
-    if (!state)
+function getExplicitGoalBudgetExhaustion(state) {
+    if (!state || state.status !== "active")
         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;
+    if (state.tokenBudget !== undefined && (state.tokensUsed ?? 0) >= state.tokenBudget) {
+        return `token budget exhausted (${state.tokensUsed ?? 0}/${state.tokenBudget})`;
+    }
+    return undefined;
 }
 /**
  * Maps a non-"continue" continuation action onto the loop's own stopReason vocabulary.
@@ -84,16 +46,21 @@ export class GoalLoopController {
         if (snapshot.continuation.action !== "continue") {
             return { submitted: false, snapshot };
         }
-        const prompt = buildGoalContinuationPrompt({ snapshot, limits: options.promptLimits });
+        const prompt = buildGoalContinuationPrompt();
         await this.deps.prompt(prompt.text, {
             expandPromptTemplates: false,
             processSlashCommands: false,
             autoContinueGoal: false,
+            internalContextType: GOAL_CONTINUATION_TRIGGER_CUSTOM_TYPE,
         });
         return { submitted: true, snapshot, prompt };
     }
     async continueGoalLoop(options) {
+        if (!Number.isSafeInteger(options.maxTurns) || options.maxTurns < 0) {
+            throw new Error("Goal continuation maxTurns must be a non-negative safe integer; 0 means unbounded.");
+        }
         let turnsSubmitted = 0;
+        const hasExplicitTurnLimit = options.maxTurns > 0;
         const now = options.now ?? Date.now;
         const maxWallClockMs = typeof options.maxWallClockMinutes === "number" && options.maxWallClockMinutes > 0
             ? options.maxWallClockMinutes * 60_000
@@ -101,45 +68,50 @@ export class GoalLoopController {
         const startedAt = now();
         const hasReachedWallClockBudget = () => maxWallClockMs !== undefined && now() - startedAt >= maxWallClockMs;
         const snapshot = () => this.deps.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });
-        if (options.maxTurns <= 0) {
-            return {
-                turnsSubmitted: 0,
-                stopReason: "max_turns_reached",
-                finalSnapshot: snapshot(),
-            };
-        }
         if (hasReachedWallClockBudget()) {
             return { turnsSubmitted, stopReason: "wall_clock_budget_reached", finalSnapshot: snapshot() };
         }
-        while (turnsSubmitted < options.maxTurns) {
+        while (!hasExplicitTurnLimit || turnsSubmitted < options.maxTurns) {
             const beforeSnapshot = snapshot();
             if (beforeSnapshot.continuation.action !== "continue") {
                 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 };
+            // Owner-supplied durable token budget — read fresh every pass so an invocation stops as
+            // soon as its own latest persisted usage crosses the explicit ceiling.
+            const beforeBudgetExhaustion = getExplicitGoalBudgetExhaustion(beforeSnapshot.goalState);
+            if (beforeBudgetExhaustion) {
+                this.deps.markGoalBudgetLimited(beforeBudgetExhaustion);
+                return { turnsSubmitted, stopReason: "goal_budget_exhausted", finalSnapshot: snapshot() };
             }
-            const beforeKey = goalProgressSignature(beforeSnapshot.goalState);
             const passStartedAt = now();
-            const result = await this.continueGoalOnce(options);
+            const usageCursor = this.deps.captureUsageCursor();
+            let result;
+            try {
+                result = await this.continueGoalOnce(options);
+            }
+            catch (error) {
+                turnsSubmitted++;
+                this.deps.recordGoalContinuationPass({ turns: 1, wallClockMs: now() - passStartedAt, usageCursor });
+                this.deps.recordGoalContinuationFailure(error);
+                throw error;
+            }
             if (result.submitted) {
                 turnsSubmitted++;
-                this.deps.recordGoalContinuationPass({ turns: 1, wallClockMs: now() - passStartedAt });
+                this.deps.recordGoalContinuationPass({ turns: 1, wallClockMs: now() - passStartedAt, usageCursor });
             }
             if (hasReachedWallClockBudget()) {
                 return { turnsSubmitted, stopReason: "wall_clock_budget_reached", finalSnapshot: snapshot() };
             }
-            const afterSnapshot = snapshot();
+            let afterSnapshot = snapshot();
+            const afterBudgetExhaustion = getExplicitGoalBudgetExhaustion(afterSnapshot.goalState);
+            if (afterBudgetExhaustion) {
+                this.deps.markGoalBudgetLimited(afterBudgetExhaustion);
+                afterSnapshot = snapshot();
+                return { turnsSubmitted, stopReason: "goal_budget_exhausted", finalSnapshot: afterSnapshot };
+            }
             if (afterSnapshot.continuation.action !== "continue") {
                 return { turnsSubmitted, stopReason: nonContinueStopReason(afterSnapshot), finalSnapshot: afterSnapshot };
             }
-            const afterKey = goalProgressSignature(afterSnapshot.goalState);
-            if (beforeKey === afterKey) {
-                return { turnsSubmitted, stopReason: "goal_state_not_advanced", finalSnapshot: afterSnapshot };
-            }
         }
         return {
             turnsSubmitted,