@cat-factory/orchestration 0.302.1 → 0.303.0

package/dist/modules/environments/environmentProbeStage.js

@@ -0,0 +1,181 @@
+import { noopLogger, redactSecrets } from '@cat-factory/kernel';
+import { coerceEnvironmentProbeReport, environmentProbeSurfaceFor, reachabilityNote, } from '@cat-factory/contracts';
+/**
+ * What a BROKEN dry run says, ahead of the container's own message.
+ *
+ * The run record has ONE error field, so without this a container that vanished and a model that
+ * errored read identically to the developer who has to decide whether pressing the button again
+ * is worth anything. Not an exhaustive `Record` over the failure vocabulary: only these arrive on
+ * this path (the dispatcher maps everything else through `failureKindFromHarnessCause`), and the
+ * default is a true statement about every one of the rest rather than a hole.
+ */
+function probeFailureCause(kind) {
+    switch (kind) {
+        case 'evicted':
+            return ('The dry run container vanished before it reported (an eviction or a crash), so nothing ' +
+                'was established about the environment. Re-running gets a fresh container.');
+        case 'harness_shutdown':
+            return ('The dry run container was shut down while the agent was still working, so nothing was ' +
+                'established about the environment.');
+        case 'timeout':
+            return ('The dry run passed its watchdog before reporting, so nothing was established about the ' +
+                'environment.');
+        default:
+            return 'The dry-run agent failed before it produced a report.';
+    }
+}
+export class EnvironmentProbeStage {
+    deps;
+    /** The injected logger, normalised once so every site can log unconditionally (CLAUDE.md). */
+    log;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.logger ?? noopLogger;
+    }
+    /**
+     * Which prober a frame's dry run would run, through the shared rule the SPA's button label
+     * reads. Pure, so ADMISSION can ask it with the frame it has already loaded and no record yet.
+     */
+    surfaceFor(frame) {
+        return environmentProbeSurfaceFor(frame.type);
+    }
+    /**
+     * Whether this deployment can actually run `surface`'s prober for this workspace, asked at
+     * admission. Delegated to the agent, which is where the runner backend is known; see the port
+     * for why an unknown answers yes.
+     */
+    async supports(workspaceId, surface) {
+        return this.deps.agent.supports(workspaceId, surface);
+    }
+    /**
+     * The frame this run is probing, read ONCE per tick, with the prober its type selects.
+     *
+     * One read rather than one per collaborator: the surface decides which container the job runs
+     * in and the title and description go into the prompt, and two reads a moment apart can observe
+     * two different frames, so a rename between them puts a service name in the prompt that does not
+     * match the surface the claim pinned. The caller PINS the surface on the run at the claim
+     * (`probeSurface`) and passes the pinned value back to {@link dispatch}: every later poll and
+     * reclaim must address the container that actually started, not one re-derived from a frame that
+     * may since have been retyped or deleted.
+     */
+    async resolveTarget(record) {
+        const frame = await this.deps.blockRepository.get(record.workspaceId, record.blockId);
+        if (!frame) {
+            throw new Error('The service frame was deleted while the agent dry run was starting.');
+        }
+        return { frame, surface: this.surfaceFor(frame) };
+    }
+    /**
+     * Dispatch the dry run for `record`, whose environment is `ready`.
+     *
+     * Throws when anything it needs is missing, and each throw is the run's terminal error, so the
+     * messages name what a human has to fix rather than what this function could not find. The
+     * caller has already CLAIMED the probe (see `EnvironmentTestRunRecord.probeSurface`), so a throw
+     * here fails the run at the `probing` stage with the environment still up for `fail()` to
+     * reclaim.
+     */
+    async dispatch(record, surface, frame) {
+        if (!record.environmentId) {
+            throw new Error('The agent dry run has no provisioned environment to probe.');
+        }
+        const handle = await this.deps.environments.getHandleWithAccess(record.workspaceId, record.environmentId);
+        if (!handle) {
+            throw new Error('The provisioned environment could not be read back for the agent dry run.');
+        }
+        if (!handle.url) {
+            throw new Error('The environment provider exposed no URL for this environment, so there is nothing for ' +
+                'an agent to drive. Configure the handler to report the environment URL.');
+        }
+        const bound = await this.deps.resolveRunRepoContext(record.workspaceId, record.blockId);
+        if (!bound?.owner || !bound.name) {
+            throw new Error('The agent dry run needs the service repository to work out what the service exposes, ' +
+                'and no linked repository resolved for this frame.');
+        }
+        if (!record.branch) {
+            throw new Error('The agent dry run has no test branch to check out.');
+        }
+        // The same projection the engine hands a tester, so the prober and the tester cannot disagree
+        // about what the platform proved. Undefined when nothing has dialled it, which the prompt
+        // states rather than omits.
+        const reachability = reachabilityNote(handle.reachability ?? null);
+        return this.deps.agent.start({
+            workspaceId: record.workspaceId,
+            jobId: record.id,
+            blockId: record.blockId,
+            surface,
+            repo: {
+                owner: bound.owner,
+                name: bound.name,
+                // The THROWAWAY branch, not the default one: it is the tree this environment was built
+                // from, so a service whose routes or auth changed on it is described to the prober as it
+                // actually runs rather than as `main` describes it.
+                branch: record.branch,
+                ...(bound.provider ? { provider: bound.provider } : {}),
+                ...(bound.serviceDirectory ? { serviceDirectory: bound.serviceDirectory } : {}),
+            },
+            environment: {
+                url: handle.url,
+                status: handle.status,
+                ...(handle.access ? { access: handle.access } : {}),
+                ...(reachability ? { reachability } : {}),
+            },
+            service: {
+                title: frame.title,
+                ...(frame.description?.trim() ? { description: frame.description.trim() } : {}),
+            },
+            initiatedBy: record.initiatedBy,
+        });
+    }
+    /**
+     * Poll the dispatched dry run.
+     *
+     * A `failed` update THROWS rather than being reported as a verdict: an evicted container or a
+     * reply carrying no JSON is a diagnostic that never happened, and returning it as a finding
+     * would tell an operator their service is inoperable when it is the platform's own step that
+     * broke. The run then fails at the `probing` stage with the container's own error, which is the
+     * honest reading and the one the sweeper's cleanup already handles.
+     */
+    async poll(record, surface) {
+        const update = await this.deps.agent.poll({
+            workspaceId: record.workspaceId,
+            jobId: record.id,
+            surface,
+        });
+        if (update.state === 'running') {
+            return update.subtasks
+                ? { state: 'running', subtasks: update.subtasks }
+                : { state: 'running' };
+        }
+        if (update.state === 'failed') {
+            throw new Error(`${probeFailureCause(update.failureKind)} ${update.error}`);
+        }
+        const report = coerceEnvironmentProbeReport(update.report, {
+            surface,
+            ...(update.model ? { model: update.model } : {}),
+            // The report is model-authored text on its way to a persisted row and a rendered panel, and
+            // the prompt hands the agent the environment's own credential verbatim plus every sealed
+            // test secret in its shell. Asking it not to echo them is guidance; this is the boundary.
+            // Applied at the COMPOSE site so it runs before the caps, per the untrusted-text rule.
+            scrub: (value) => redactSecrets(value) ?? value,
+        });
+        this.log.info('environment dry run reported', {
+            workspaceId: record.workspaceId,
+            runId: record.id,
+            surface,
+            verdict: report.verdict,
+            attempted: report.attempted,
+            succeeded: report.succeeded,
+            authenticatedSucceeded: report.authenticatedSucceeded,
+        });
+        return { state: 'reported', report };
+    }
+    /** Reclaim the probe's container. Best-effort by contract; never throws at the caller. */
+    async release(record, surface) {
+        await this.deps.agent.stop({
+            workspaceId: record.workspaceId,
+            jobId: record.id,
+            surface,
+        });
+    }
+}
+//# sourceMappingURL=environmentProbeStage.js.map

package/dist/modules/environments/environmentProbeStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environmentProbeStage.js","sourceRoot":"","sources":["../../../src/modules/environments/environmentProbeStage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/orchestration",
-  "version": "0.302.1",
+  "version": "0.303.0",
   "description": "Delivery-workflow engine for the Agent Architecture Board (execution, bootstrap, pipelines, board, boardScan, requirements, and composition root).",
   "repository": {
     "type": "git",
@@ -24,19 +24,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@cat-factory/agents": "0.157.1",
-    "@cat-factory/caching": "0.20.72",
-    "@cat-factory/contracts": "0.347.0",
-    "@cat-factory/integrations": "0.172.7",
-    "@cat-factory/kernel": "0.338.0",
-    "@cat-factory/prompt-fragments": "1.1.34",
-    "@cat-factory/sandbox": "0.12.46",
-    "@cat-factory/spend": "0.19.0",
-    "@cat-factory/workspaces": "0.28.60",
-    "ai": "^7.0.92"
+    "@cat-factory/agents": "0.158.0",
+    "@cat-factory/caching": "0.20.74",
+    "@cat-factory/contracts": "0.348.0",
+    "@cat-factory/integrations": "0.172.9",
+    "@cat-factory/kernel": "0.340.0",
+    "@cat-factory/prompt-fragments": "1.1.36",
+    "@cat-factory/sandbox": "0.12.48",
+    "@cat-factory/spend": "0.20.1",
+    "@cat-factory/workspaces": "0.28.62",
+    "ai": "^7.0.93"
   },
   "devDependencies": {
-    "@cat-factory/sandbox-fixtures": "0.8.30",
+    "@cat-factory/sandbox-fixtures": "0.8.31",
     "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },