@cat-factory/server 0.325.1 → 0.326.0

package/dist/agents/CompositeAgentExecutor.d.ts

@@ -1,12 +1,24 @@
-import { type AgentExecutor, type AgentJobHandle, type AgentJobUpdate, type AgentRunContext, type AgentRunResult, type AsyncAgentExecutor, type RunReclaimTarget } from '@cat-factory/kernel';
+import { type AgentExecutor, type AgentJobHandle, type AgentJobUpdate, type AgentRunContext, type AgentRunResult, type AsyncAgentExecutor, type Logger, type RunReclaimReport, type RunReclaimTarget } from '@cat-factory/kernel';
 import type { DispatchToolServers } from '@cat-factory/contracts';
 import { type AgentKindRegistry } from '@cat-factory/agents';
 export declare class CompositeAgentExecutor implements AsyncAgentExecutor {
     private readonly inline;
     private readonly container;
+    private readonly delegated;
     /** The app-owned agent-kind registry: decides whether a registered custom kind needs a container. */
     private readonly registry;
-    constructor(inline: AgentExecutor, container: AgentExecutor | null, registry?: AgentKindRegistry);
+    /** Normalised once, so the one best-effort site below can log unconditionally (CLAUDE.md). */
+    private readonly log;
+    constructor(inline: AgentExecutor, container: AgentExecutor | null, registry?: AgentKindRegistry, delegated?: AgentExecutor | null, logger?: Logger);
+    /**
+     * The delegated executor for this kind, or undefined when the kind does not run on one.
+     *
+     * Refuses LOUDLY rather than falling through when a delegated kind's arm is unwired, for exactly
+     * the reason the container arm does: the fallback is an inline LLM call over an implementer's
+     * prompt, which produces confident prose and no branch, and the run then advances into a `ci`
+     * gate with nothing to check.
+     */
+    private delegatedFor;
     /**
      * The executor that handles a given step's kind. Container kinds REQUIRE a real
      * sandbox: with none wired we throw rather than fall back to the inline executor,
@@ -44,7 +56,14 @@ export declare class CompositeAgentExecutor implements AsyncAgentExecutor {
      * container executor) when stopping a run, so the composite must forward the reclaim
      * to the container — otherwise the Layer-2 reclaim silently no-ops and leaks a
      * warm instance. Delegates only when a container that supports it is wired.
+     *
+     * The two arms are INDEPENDENT resources, so the second must not be gated on the first
+     * succeeding. A container reclaim that throws (a DO/EKS API error, a runner-pool timeout: what
+     * "best-effort" here was written for) would otherwise propagate out before the delegated arm
+     * runs, and `applyDelegationCancellation` would then mark every live delegation "could not stop
+     * the external work" while the executor that COULD stop it was never asked. The external run
+     * carries on, opens its pull request and bills its tokens.
      */
-    reclaimRun(target: RunReclaimTarget): Promise<void>;
+    reclaimRun(target: RunReclaimTarget): Promise<RunReclaimReport | void>;
 }
 //# sourceMappingURL=CompositeAgentExecutor.d.ts.map

package/dist/agents/CompositeAgentExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CompositeAgentExecutor.d.ts","sourceRoot":"","sources":["../../src/agents/CompositeAgentExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EAEvB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,qBAAqB,CAAA;AAwB5B,qBAAa,sBAAuB,YAAW,kBAAkB;IAK7D,OAAO,CAAC,QAAQ,CAAC,MAAM;IAGvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAP5B,qGAAqG;IACrG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAE5C,YACmB,MAAM,EAAE,aAAa,EAGrB,SAAS,EAAE,aAAa,GAAG,IAAI,EAGhD,QAAQ,GAAE,iBAA8C,EAGzD;IAED;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAqBZ,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAErD;IAED;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGlE;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAGrF;IAED;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAIvD;IAED,+EAA+E;IAC/E,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAG3C;IAED,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAM1D;IAED,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAMvD;IAED;;;;;OAKG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxD;CACF"}
+{"version":3,"file":"CompositeAgentExecutor.d.ts","sourceRoot":"","sources":["../../src/agents/CompositeAgentExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EAEvB,KAAK,MAAM,EAGX,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EACL,KAAK,iBAAiB,EAIvB,MAAM,qBAAqB,CAAA;AA8B5B,qBAAa,sBAAuB,YAAW,kBAAkB;IAO7D,OAAO,CAAC,QAAQ,CAAC,MAAM;IAGvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAQ1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAjB5B,qGAAqG;IACrG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,8FAA8F;IAC9F,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAE5B,YACmB,MAAM,EAAE,aAAa,EAGrB,SAAS,EAAE,aAAa,GAAG,IAAI,EAGhD,QAAQ,GAAE,iBAA8C,EAKvC,SAAS,GAAE,aAAa,GAAG,IAAW,EACvD,MAAM,CAAC,EAAE,MAAM,EAIhB;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAYpB;;;;OAIG;IACH,OAAO,CAAC,IAAI;IA4BZ,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAErD;IAED;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGlE;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAGrF;IAED;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvD;IAED,+EAA+E;IAC/E,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAG3C;IAED,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAM1D;IAED,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAkBvD;IAED;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAyB3E;CACF"}

package/dist/agents/CompositeAgentExecutor.js

@@ -1,5 +1,5 @@
-import { isAsyncAgentExecutor, } from '@cat-factory/kernel';
-import { defaultAgentKindRegistry, runsInContainer, } from '@cat-factory/agents';
+import { isAsyncAgentExecutor, noopLogger, runBestEffort, } from '@cat-factory/kernel';
+import { defaultAgentKindRegistry, runsDelegated, runsInContainer, } from '@cat-factory/agents';
 // Routes each pipeline step to the right executor by agent kind. The kinds that
 // produce and commit files against a real checkout — implementation (`coder`),
 // the external-dependency mock builder (`mocker`), the Playwright e2e test
@@ -21,21 +21,55 @@ import { defaultAgentKindRegistry, runsInContainer, } from '@cat-factory/agents'
 // Runtime-neutral: both the Cloudflare Worker and the Node service wire this
 // composite (inline `AiAgentExecutor` + a container executor backed by a
 // per-run Cloudflare Container or an org's self-hosted runner pool).
+//
+// A THIRD arm routes a `delegated` kind to the deployment's own external executor (see
+// `DelegatedAgentExecutor`). It is keyed off the agent-kind registry exactly as the container arm
+// is, and it is the reason `pollJob` no longer hard-routes to the container: a poll rebuilds its
+// handle from the step alone, so the arm has to be re-derived from the SAME declaration the
+// dispatch routed on rather than assumed.
 export class CompositeAgentExecutor {
     inline;
     container;
+    delegated;
     /** The app-owned agent-kind registry: decides whether a registered custom kind needs a container. */
     registry;
+    /** Normalised once, so the one best-effort site below can log unconditionally (CLAUDE.md). */
+    log;
     constructor(inline, 
     // null when no sandbox is wired — container kinds then fail loudly (see below)
     // rather than silently degrading to a useless one-shot inline call.
     container, 
     // The app-owned agent-kind registry; defaults to the built-ins-only registry when a
     // facade doesn't inject the shared instance (tests / no custom kinds).
-    registry = defaultAgentKindRegistry()) {
+    registry = defaultAgentKindRegistry(), 
+    // The deployment's external executors, or null when the facade wired none. Null is the
+    // ordinary state: the platform ships no delegated kind, so nothing reaches this arm unless a
+    // deployment registered one, and a kind that does with no executor wired fails loudly for the
+    // reason an unwired container kind does.
+    delegated = null, logger) {
         this.inline = inline;
         this.container = container;
+        this.delegated = delegated;
         this.registry = registry;
+        this.log = logger ?? noopLogger;
+    }
+    /**
+     * The delegated executor for this kind, or undefined when the kind does not run on one.
+     *
+     * Refuses LOUDLY rather than falling through when a delegated kind's arm is unwired, for exactly
+     * the reason the container arm does: the fallback is an inline LLM call over an implementer's
+     * prompt, which produces confident prose and no branch, and the run then advances into a `ci`
+     * gate with nothing to check.
+     */
+    delegatedFor(agentKind) {
+        if (!runsDelegated(agentKind, this.registry))
+            return undefined;
+        if (!this.delegated) {
+            throw new Error(`Agent kind '${agentKind}' runs on an external (delegated) executor, and this ` +
+                'deployment wired none. Register the executor on the delegated-executor registry and ' +
+                'pass it to the facade entry point.');
+        }
+        return this.delegated;
     }
     /**
      * The executor that handles a given step's kind. Container kinds REQUIRE a real
@@ -43,6 +77,14 @@ export class CompositeAgentExecutor {
      * because a one-shot LLM call cannot operate on repo contents.
      */
     pick(context) {
+        // A DELEGATED kind's work happens in a system the deployment already runs. Asked FIRST,
+        // because the two predicates below both answer "no" for it and the inline arm is what it would
+        // otherwise fall through to: a one-shot LLM call, over a prompt written for an implementer,
+        // producing plausible text and no branch. Routed off the same registry declaration the engine
+        // reads, so what the pipeline builder labelled as leaving the platform is what leaves it.
+        const delegated = this.delegatedFor(context.agentKind);
+        if (delegated)
+            return delegated;
         // Built-in container kinds, plus any custom kind a deployment registered with
         // `requiresContainer: true` (e.g. a proprietary org package contributing a
         // repo-operating agent) and the container-backed companions, need a real checkout;
@@ -91,6 +133,11 @@ export class CompositeAgentExecutor {
      * without the capability all report false (budget-metered, the prior behaviour).
      */
     isQuotaBased(context) {
+        // A DELEGATED step spends nothing of ours: no pooled token is leased and no proxy call is
+        // metered. Answered before the container check below, which would otherwise read its `false`
+        // as "budget-metered" and let the spend gate account for tokens nobody here can see.
+        if (runsDelegated(context.agentKind, this.registry))
+            return Promise.resolve(false);
         if (!this.container)
             return Promise.resolve(false);
         if (!runsInContainer(context.agentKind, this.registry))
@@ -110,7 +157,17 @@ export class CompositeAgentExecutor {
         return executor.startJob(context);
     }
     pollJob(handle) {
-        // Only the container executor runs async jobs, so polls route there.
+        // ROUTED, not assumed. A poll rebuilds its handle from the persisted step, and a delegated
+        // step's `delegated` record is what says the work is somewhere else. Read it here rather than
+        // hard-routing to the container, which would poll a container that was never started and
+        // settle the step against nothing.
+        if (handle.delegated) {
+            if (!this.delegated || !isAsyncAgentExecutor(this.delegated)) {
+                throw new Error(`This run has work on the external executor '${handle.delegated.executor}' and this ` +
+                    'deployment wired no delegated executor to poll it with.');
+            }
+            return this.delegated.pollJob(handle);
+        }
         if (!this.container || !isAsyncAgentExecutor(this.container)) {
             throw new Error('Container executor does not support async jobs');
         }
@@ -121,11 +178,40 @@ export class CompositeAgentExecutor {
      * container executor) when stopping a run, so the composite must forward the reclaim
      * to the container — otherwise the Layer-2 reclaim silently no-ops and leaks a
      * warm instance. Delegates only when a container that supports it is wired.
+     *
+     * The two arms are INDEPENDENT resources, so the second must not be gated on the first
+     * succeeding. A container reclaim that throws (a DO/EKS API error, a runner-pool timeout: what
+     * "best-effort" here was written for) would otherwise propagate out before the delegated arm
+     * runs, and `applyDelegationCancellation` would then mark every live delegation "could not stop
+     * the external work" while the executor that COULD stop it was never asked. The external run
+     * carries on, opens its pull request and bills its tokens.
      */
     async reclaimRun(target) {
         if (this.container && isAsyncAgentExecutor(this.container) && this.container.reclaimRun) {
-            await this.container.reclaimRun(target);
+            const reclaim = this.container.reclaimRun.bind(this.container);
+            await runBestEffort(this.log, 'composite.reclaimContainer', () => reclaim(target), {
+                runId: target.runId,
+            });
+        }
+        // BOTH arms, always, and the second one ANSWERS. A run can hold a container and external work
+        // at once (a delegated implementer followed by a container fixer), so reclaiming one is not
+        // reclaiming the run; and whether the external half actually stopped is a fact only its
+        // executor knows, which is what the report carries back to the record.
+        if (!target.delegations?.length)
+            return;
+        if (this.delegated && isAsyncAgentExecutor(this.delegated) && this.delegated.reclaimRun) {
+            return this.delegated.reclaimRun(target);
         }
+        // Named rather than dropped: the run is being torn down with external work still running and
+        // nothing here able to stop it, which is precisely the state the record must not render as a
+        // clean teardown.
+        return {
+            delegations: target.delegations.map((handle) => ({
+                correlationKey: handle.correlationKey,
+                cancelled: false,
+                note: 'This deployment wired no delegated executor, so the external work was left running.',
+            })),
+        };
     }
 }
 //# sourceMappingURL=CompositeAgentExecutor.js.map

package/dist/agents/CompositeAgentExecutor.js.map

@@ -1 +1 @@
-{"version":3,"file":"CompositeAgentExecutor.js","sourceRoot":"","sources":["../../src/agents/CompositeAgentExecutor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CompositeAgentExecutor.js","sourceRoot":"","sources":["../../src/agents/CompositeAgentExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,oBAAoB,EAEpB,UAAU,EACV,aAAa,GAGd,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAEL,wBAAwB,EACxB,aAAa,EACb,eAAe,GAChB,MAAM,qBAAqB,CAAA;AAE5B,gFAAgF;AAChF,+EAA+E;AAC/E,2EAA2E;AAC3E,kFAAkF;AAClF,gFAAgF;AAChF,oFAAoF;AACpF,kFAAkF;AAClF,mEAAmE;AACnE,gFAAgF;AAChF,sFAAsF;AACtF,6EAA6E;AAC7E,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,kFAAkF;AAClF,kFAAkF;AAClF,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,qEAAqE;AACrE,EAAE;AACF,uFAAuF;AACvF,kGAAkG;AAClG,iGAAiG;AACjG,4FAA4F;AAC5F,0CAA0C;AAE1C,MAAM,OAAO,sBAAsB;IAOd,MAAM;IAGN,SAAS;IAQT,SAAS;IAjB5B,qGAAqG;IACpF,QAAQ,CAAmB;IAC5C,8FAA8F;IAC7E,GAAG,CAAQ;IAE5B,YACmB,MAAqB;IACtC,+EAA+E;IAC/E,oEAAoE;IACnD,SAA+B;IAChD,oFAAoF;IACpF,uEAAuE;IACvE,QAAQ,GAAsB,wBAAwB,EAAE;IACxD,uFAAuF;IACvF,6FAA6F;IAC7F,8FAA8F;IAC9F,yCAAyC;IACxB,SAAS,GAAyB,IAAI,EACvD,MAAe;sBAZE,MAAM;yBAGN,SAAS;yBAQT,SAAS;QAG1B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,GAAG,GAAG,MAAM,IAAI,UAAU,CAAA;IACjC,CAAC;IAED;;;;;;;OAOG;IACK,YAAY,CAAC,SAAiB;QACpC,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,SAAS,CAAA;QAC9D,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,eAAe,SAAS,uDAAuD;gBAC7E,sFAAsF;gBACtF,oCAAoC,CACvC,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED;;;;OAIG;IACK,IAAI,CAAC,OAAwB;QACnC,wFAAwF;QACxF,+FAA+F;QAC/F,4FAA4F;QAC5F,8FAA8F;QAC9F,0FAA0F;QAC1F,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QACtD,IAAI,SAAS;YAAE,OAAO,SAAS,CAAA;QAC/B,8EAA8E;QAC9E,2EAA2E;QAC3E,mFAAmF;QACnF,wEAAwE;QACxE,qFAAqF;QACrF,oFAAoF;QACpF,uEAAuE;QACvE,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC,MAAM,CAAA;QAC1E,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,eAAe,OAAO,CAAC,SAAS,iDAAiD;gBAC/E,kFAAkF;gBAClF,8EAA8E;gBAC9E,+EAA+E;gBAC/E,0BAA0B,CAC7B,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,GAAG,CAAC,OAAwB;QAC1B,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACxC,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,OAAwB;QACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACnC,OAAO,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IACvE,CAAC;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,OAAwB;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACnC,OAAO,QAAQ,CAAC,kBAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC7E,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,OAAwB;QACnC,0FAA0F;QAC1F,6FAA6F;QAC7F,qFAAqF;QACrF,IAAI,aAAa,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAClF,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAClD,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QACrF,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACzE,CAAC;IAED,+EAA+E;IAC/E,SAAS,CAAC,OAAwB;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACnC,OAAO,oBAAoB,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IACtE,CAAC;IAED,QAAQ,CAAC,OAAwB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACnC,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,qCAAqC,OAAO,CAAC,SAAS,GAAG,CAAC,CAAA;QAC5E,CAAC;QACD,OAAO,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IACnC,CAAC;IAED,OAAO,CAAC,MAAsB;QAC5B,2FAA2F;QAC3F,8FAA8F;QAC9F,yFAAyF;QACzF,mCAAmC;QACnC,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC7D,MAAM,IAAI,KAAK,CACb,+CAA+C,MAAM,CAAC,SAAS,CAAC,QAAQ,aAAa;oBACnF,yDAAyD,CAC5D,CAAA;YACH,CAAC;YACD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACvC,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;QACnE,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,UAAU,CAAC,MAAwB;QACvC,IAAI,IAAI,CAAC,SAAS,IAAI,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;YACxF,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YAC9D,MAAM,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,4BAA4B,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;gBACjF,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC,CAAA;QACJ,CAAC;QACD,8FAA8F;QAC9F,4FAA4F;QAC5F,wFAAwF;QACxF,uEAAuE;QACvE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM;YAAE,OAAM;QACvC,IAAI,IAAI,CAAC,SAAS,IAAI,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;YACxF,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;QAC1C,CAAC;QACD,6FAA6F;QAC7F,6FAA6F;QAC7F,kBAAkB;QAClB,OAAO;YACL,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAC/C,cAAc,EAAE,MAAM,CAAC,cAAc;gBACrC,SAAS,EAAE,KAAK;gBAChB,IAAI,EAAE,qFAAqF;aAC5F,CAAC,CAAC;SACJ,CAAA;IACH,CAAC;CACF"}

package/dist/agents/DelegatedAgentExecutor.d.ts

@@ -0,0 +1,147 @@
+import { type AgentContextRecorder, type AgentJobHandle, type AgentJobUpdate, type AgentRunContext, type AgentRunResult, type AsyncAgentExecutor, type Clock, type DelegatedExecutorDeps, type DelegatedExecutorRegistry, type DelegatedRepoFilesResolver, type Logger, type RunReclaimReport, type RunReclaimTarget, type TaskRepository, type ToolSecretResolver } from '@cat-factory/kernel';
+import type { AgentKindRegistry } from '@cat-factory/agents';
+import type { ResolveRepoTarget, ResolveRepoOrigin } from './repoTargeting.js';
+/** What the facade wires for the delegated path. */
+export interface DelegatedAgentExecutorDependencies {
+    /** The app-owned registry of the deployment's external executors. */
+    delegatedExecutorRegistry: DelegatedExecutorRegistry;
+    /** The app-owned agent-kind registry: which kinds are delegated, and to which executor. */
+    agentKindRegistry: AgentKindRegistry;
+    /** The run's repo target (the service↔repo projection), the same resolver the container uses. */
+    resolveRepoTarget: ResolveRepoTarget;
+    /**
+     * Where the repo is reached: the clone URL plus the VCS provider.
+     *
+     * REQUIRED, with no GitHub default. A default is invisible when it is wrong: a GitLab-hosted
+     * deployment whose facade forgot to wire this handed every brief a `https://github.com/...`
+     * clone URL for a repository that does not live there, and the provider-mismatch refusal that
+     * exists to catch exactly that never ran. A facade with genuinely nothing else to resolve
+     * passes `githubRepoOrigin` by name, which says so.
+     */
+    resolveRepoOrigin: ResolveRepoOrigin;
+    /**
+     * Where the work came from, when it came from a tracker. One read per dispatch off the block's
+     * linked issues, never a per-issue loop, and never re-read on a poll.
+     */
+    taskRepository?: TaskRepository;
+    /**
+     * Resolves an executor's declared credentials for this workspace. Absent ⇒ every executor is
+     * called with an empty bag, which is exactly what a deployment that declared none expects and
+     * what one that declared some will see as its own system refusing the call.
+     */
+    resolveToolSecrets?: ToolSecretResolver;
+    /** Files the dispatch's agent-context snapshot; absent ⇒ nothing is recorded. */
+    agentContextObservability?: AgentContextRecorder;
+    /** The bound deps every registered executor is BUILT over. */
+    executorDeps: DelegatedExecutorDeps;
+    /**
+     * The checkout-free repo binding the engine writes a `platform-creates` work branch through.
+     *
+     * The SAME resolver `executorDeps.repoFiles` carries, named here as its own dependency because
+     * the engine's use of it is not the executor's: reaching into another collaborator's bundle is
+     * how the two come to disagree about which binding is live. Absent ⇒ this deployment configured
+     * no VCS provider, which refuses a `platform-creates` DISPATCH and nothing else.
+     */
+    resolveRepoFiles?: DelegatedRepoFilesResolver;
+    logger: Logger;
+    clock: Clock;
+}
+/**
+ * Runs a `delegated`-surface step on a registered external executor.
+ *
+ * Async by construction: an external run is polled, never awaited, which is the same shape the
+ * container executor has and the reason both durable drivers already know how to drive it.
+ */
+export declare class DelegatedAgentExecutor implements AsyncAgentExecutor {
+    private readonly deps;
+    private readonly log;
+    /**
+     * Built executors, memoised per id for the life of this instance.
+     *
+     * A definition's `create` may build a client, and this executor is constructed once per app
+     * (per isolate on the Worker), so building per dispatch would discard whatever an executor
+     * warmed. Memoising on the INSTANCE rather than a module map is what keeps it out of the
+     * module-global trap every registry in this codebase is built to avoid.
+     */
+    private readonly built;
+    constructor(deps: DelegatedAgentExecutorDependencies);
+    /** Every delegated step is polled: an external run outlives any request of ours. */
+    runsAsync(_context: AgentRunContext): boolean;
+    /**
+     * A delegated step resolves NO model, and that is the honest answer rather than a gap.
+     *
+     * The external executor picks its own, through its own credentials, and the platform never sees
+     * it. Returning a guess would put a model on the board that nothing ran, and every reader
+     * downstream (the run card, the spend rollup, the debug overview) would treat it as the thing
+     * that spent the tokens it also cannot see.
+     */
+    resolveModel(_context: AgentRunContext): Promise<string | undefined>;
+    /**
+     * Not quota-based. A delegated run spends nothing of OURS: no pooled subscription token is
+     * leased and no proxy call is metered, so it is neither quota nor budget.
+     */
+    isQuotaBased(_context: AgentRunContext): Promise<boolean>;
+    /**
+     * Start (or RE-ATTACH to) this step's external work.
+     *
+     * Idempotent per correlation key, which is what the port asks of every executor and what the
+     * engine's claim-before-effect makes possible on this side: the key is derived from the run, the
+     * kind and the dispatch epoch, so a replayed dispatch produces the same key and the executor is
+     * asked to recognise its own run rather than start another.
+     */
+    startJob(context: AgentRunContext): Promise<AgentJobHandle>;
+    /**
+     * Poll the external work, re-resolving the executor's credentials FIRST.
+     *
+     * Re-resolved rather than carried on the handle, and that is not a caching miss: a delegated
+     * poll can run hours after the dispatch, a GitHub App token lives one hour, and a credential
+     * frozen at dispatch would be dead exactly on the long runs this executor class exists for.
+     */
+    pollJob(handle: AgentJobHandle): Promise<AgentJobUpdate>;
+    /**
+     * Stop every delegated unit this run holds, and REPORT what that achieved.
+     *
+     * The report is the point. An executor that declares no `cancel` leaves its run alive: it will
+     * finish, open its pull request and bill its tokens long after the platform recorded this run as
+     * stopped, and the person who stopped it is the one who needs to know to go and stop it there.
+     * Best-effort throughout (a teardown must never propagate) but never SILENT: a failure to
+     * cancel is reported as "not cancelled" with its cause, which is a different fact from a clean
+     * stop and renders differently on the step.
+     */
+    reclaimRun(target: RunReclaimTarget): Promise<RunReclaimReport | void>;
+    /**
+     * A delegated step cannot be run SYNCHRONOUSLY: `run()` exists for non-durable callers and
+     * tests, and an external system that answers in hours is exactly what that shape cannot serve.
+     * Refused loudly rather than looped in-process, which would hold a request open for the duration
+     * of somebody else's CI.
+     */
+    run(context: AgentRunContext): Promise<AgentRunResult>;
+    private cancelOne;
+    /** The registered definition for a kind, refusing the two ways it can be missing. */
+    private requireDefinition;
+    private executorFor;
+    /**
+     * Honour the executor's {@link DelegatedExecutorDefinition.workBranch} declaration.
+     *
+     * `executor-creates` writes nothing and probes nothing, which is what keeps a run whose external
+     * work never landed from leaving an empty ref behind.
+     */
+    private prepareWorkBranch;
+    /**
+     * Resolve the repo + branches this dispatch targets, then compose the brief over them.
+     *
+     * `aprioriWork` rides back out because the brief carries the branch NAME and not who is allowed
+     * to create it, and only this method knows which of the two answers produced the name.
+     */
+    private composeBrief;
+    /**
+     * Where the work came from, when it came from a tracker: ONE batch read of the block's linked
+     * issues, and the first live one.
+     *
+     * First rather than all, because the brief names the ticket the work is FOR and a block carries
+     * one such link by construction (`claimBlockLink` makes "one task per ticket" an invariant). Any
+     * further attachments are reference material, and they already reach the agent as context files.
+     */
+    private resolveTrackerRef;
+}
+//# sourceMappingURL=DelegatedAgentExecutor.d.ts.map

package/dist/agents/DelegatedAgentExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DelegatedAgentExecutor.d.ts","sourceRoot":"","sources":["../../src/agents/DelegatedAgentExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,KAAK,EAGV,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAI/B,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAO5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAoB9E,oDAAoD;AACpD,MAAM,WAAW,kCAAkC;IACjD,qEAAqE;IACrE,yBAAyB,EAAE,yBAAyB,CAAA;IACpD,2FAA2F;IAC3F,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,iGAAiG;IACjG,iBAAiB,EAAE,iBAAiB,CAAA;IACpC;;;;;;;;OAQG;IACH,iBAAiB,EAAE,iBAAiB,CAAA;IACpC;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;IACvC,iFAAiF;IACjF,yBAAyB,CAAC,EAAE,oBAAoB,CAAA;IAChD,8DAA8D;IAC9D,YAAY,EAAE,qBAAqB,CAAA;IACnC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,0BAA0B,CAAA;IAC7C,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAA;CACb;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,kBAAkB;IAYnD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAXjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAE7D,YAA6B,IAAI,EAAE,kCAAkC,EAEpE;IAED,oFAAoF;IACpF,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAE5C;IAED;;;;;;;OAOG;IACH,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAEnE;IAED;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAExD;IAED;;;;;;;OAOG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAuGhE;IAED;;;;;;OAMG;IACG,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CA4C7D;IAED;;;;;;;;;OASG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAK3E;IAED;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAWrD;YAEa,SAAS;IAiDvB,qFAAqF;IACrF,OAAO,CAAC,iBAAiB;IAyBzB,OAAO,CAAC,WAAW;IAQnB;;;;;OAKG;YACW,iBAAiB;IAc/B;;;;;OAKG;YACW,YAAY;IAkD1B;;;;;;;OAOG;YACW,iBAAiB;CAehC"}