@cats-inc/cats-platform 0.1.21 → 0.3.4

package/build/server/products/work/state/workGoldenPathRuntimeExecutor.js

@@ -0,0 +1,239 @@
+/**
+ * The runtime-backed step executor for the golden path (SPEC-114 FR-28).
+ *
+ * Execution goes through one supervised `cats-runtime` session for the whole
+ * run: step 0 opens it with the goal and acceptance criteria, and every later
+ * step continues the same session with what is still missing. A Telegram
+ * handler never starts a provider session itself.
+ *
+ * The executor deliberately never reports completion. It returns
+ * `claims_complete` on every successful turn and lets the runner's evidence
+ * check decide, which is what keeps FR-30 true no matter what the model says.
+ */
+import { resolveFullResponseText } from '../../../platform/runtime/client.js';
+import { createSupervisedRuntimeSession, RuntimeSupervisionRejectedError, sendSupervisedRuntimeMessage, } from '../../../platform/supervision/runtimeBoundary.js';
+import { parseClaimedCriteria } from './workGoldenPathDeliveryEvidence.js';
+export const noEvidenceCollector = async () => ({
+    satisfiedCriteria: [],
+    artifact: null,
+    commit: null,
+});
+const DEFAULT_ACTOR_REF = 'actor-work-golden-path';
+/**
+ * Provider-independent spellings used by cats-runtime adapters for local file
+ * inspection and mutation. Shell, git, network, browser, MCP, and delegation
+ * tools are deliberately absent; Cats owns commit/publish side effects.
+ */
+const GOLDEN_PATH_LOCAL_FILE_TOOLS = [
+    'Read',
+    'Glob',
+    'Grep',
+    'Edit',
+    'Write',
+    'read_file',
+    'list_dir',
+    'search',
+    'edit',
+    'write',
+    'fileChange',
+    'file_change',
+    'apply_patch',
+];
+/**
+ * Rejection codes that mean "the envelope is too narrow", as opposed to "the
+ * call went wrong". Budget exhaustion and approval gates are deliberately not
+ * here: they are different conversations with the owner.
+ */
+const PERMISSION_REJECTION_CODES = new Set([
+    'E_TOOL_SCOPE_DENIED',
+    'E_NOT_AUTHORIZED',
+]);
+/**
+ * Every runtime call is made through the supervision boundary rather than the
+ * raw client, so budget, policy scope, and tool evidence apply to a golden-path
+ * run exactly as they do to any other supervised work.
+ */
+function buildSupervisionContext(input) {
+    return {
+        product: 'cats-work',
+        surface: 'transport-work-golden-path',
+        runId: input.runId,
+        actionId: `${input.runId}:step-${input.stepIndex}:${input.toolReason}`,
+        actorRef: input.actorRef,
+        reason: input.toolReason,
+        policyToolScope: input.policyToolScope,
+    };
+}
+function buildOpeningInstruction(context) {
+    const criteria = context.acceptanceCriteria.length > 0
+        ? context.acceptanceCriteria.map((entry) => `- ${entry}`).join('\n')
+        : '- (none stated; report what you changed)';
+    return [
+        `Goal: ${context.goal}`,
+        '',
+        'Done when:',
+        criteria,
+        '',
+        `Delivery mode: ${context.deliveryMode}`,
+        'Work only inside the provided workspace. Do not declare the task complete;',
+        ...(context.deliveryMode !== 'artifact_only'
+            ? ['Cats will stage and commit the isolated worktree after verifying your response.']
+            : []),
+        'Cats verifies delivery evidence itself. For each criterion you believe now',
+        'holds, end your reply with a line of exactly this form:',
+        'CRITERIA-MET: <the criterion text, copied verbatim>',
+    ].join('\n');
+}
+/**
+ * The continuation prompt.
+ *
+ * It states the gap rather than re-asking the question, so a second turn is a
+ * correction rather than a repeat of the first.
+ */
+function buildContinuationInstruction(context) {
+    const lines = [`Not accepted yet (step ${context.stepIndex + 1}).`];
+    if (context.outstandingCriteria.length > 0) {
+        lines.push('Still unmet:');
+        lines.push(...context.outstandingCriteria.map((entry) => `- ${entry}`));
+    }
+    if (context.outstandingGaps.length > 0) {
+        lines.push(`Missing evidence: ${context.outstandingGaps.join(', ')}.`);
+    }
+    lines.push('Continue until those hold, then summarize the change.');
+    return lines.join('\n');
+}
+export function createWorkGoldenPathRuntimeExecutor(input) {
+    const collectEvidence = input.collectEvidence ?? noEvidenceCollector;
+    const actorRef = input.actorRef ?? DEFAULT_ACTOR_REF;
+    const resolveToolScope = input.resolveToolScope
+        // Directly-constructed executors predate the run envelope and are used by
+        // isolated product tests. Keep their historical safe write ceiling while
+        // production always supplies the run-scoped value.
+        ?? ((context) => context.toolScope ?? 'narrow_write');
+    // One session per run, opened lazily and reused across steps so the agent
+    // keeps its context instead of restarting from scratch every turn.
+    const sessionsByRun = new Map();
+    return async (context) => {
+        try {
+            const runToolScope = resolveToolScope(context);
+            if (runToolScope !== 'narrow_write' && runToolScope !== 'broad_write') {
+                return {
+                    status: 'permission_denied',
+                    summary: 'The run is not authorized to modify an isolated workspace.',
+                    satisfiedCriteria: [],
+                    artifact: null,
+                    commit: null,
+                    blockedReason: 'workspace_write_not_authorized',
+                    denial: { toolName: 'cats.runtime.session.create', code: 'E_TOOL_SCOPE_DENIED' },
+                };
+            }
+            let session = sessionsByRun.get(context.runId) ?? null;
+            if (session === null) {
+                const target = input.resolveTarget?.(context) ?? context.executionTarget ?? null;
+                if (target === null) {
+                    return {
+                        status: 'failed',
+                        summary: 'No provider execution target was resolved for this run.',
+                        satisfiedCriteria: [],
+                        artifact: null,
+                        commit: null,
+                        blockedReason: 'execution_target_missing',
+                    };
+                }
+                session = await createSupervisedRuntimeSession({
+                    runtimeClient: input.runtimeClient,
+                    input: {
+                        provider: target.provider,
+                        instance: target.instance ?? null,
+                        model: target.model ?? null,
+                        cwd: context.workspacePath,
+                        workspaceKind: context.deliveryMode === 'artifact_only' ? 'sandbox' : 'worktree',
+                        workspaceAccess: 'read_write',
+                        permissionMode: 'whitelist',
+                        allowedTools: [...GOLDEN_PATH_LOCAL_FILE_TOOLS],
+                        context: {
+                            source: 'assignment',
+                            reason: 'work_golden_path_run',
+                            taskId: context.taskId ?? undefined,
+                            labels: ['cats-work', 'golden-path'],
+                        },
+                    },
+                    supervision: buildSupervisionContext({
+                        runId: context.runId,
+                        stepIndex: context.stepIndex,
+                        actorRef,
+                        toolReason: 'work_golden_path_session_create',
+                        // This scope authorizes the expensive orchestration call itself.
+                        // Provider tools are independently narrowed by the runtime
+                        // whitelist above.
+                        policyToolScope: 'broad_write',
+                    }),
+                });
+                sessionsByRun.set(context.runId, session);
+            }
+            const message = await sendSupervisedRuntimeMessage({
+                runtimeClient: input.runtimeClient,
+                sessionId: session.id,
+                content: context.stepIndex === 0
+                    ? buildOpeningInstruction(context)
+                    : buildContinuationInstruction(context),
+                supervision: buildSupervisionContext({
+                    runId: context.runId,
+                    stepIndex: context.stepIndex,
+                    actorRef,
+                    toolReason: 'work_golden_path_message_send',
+                    policyToolScope: 'broad_write',
+                }),
+            });
+            const summary = resolveFullResponseText(message.segments).trim();
+            const evidence = await collectEvidence({
+                runId: context.runId,
+                sessionId: session.id,
+                goal: context.goal,
+                deliveryMode: context.deliveryMode,
+                workspacePath: context.workspacePath,
+                deliveryWorkspacePath: session.cwd,
+                baselineHeadOid: context.workspaceHeadOid ?? null,
+                acceptanceCriteria: context.acceptanceCriteria,
+                claimedCriteria: parseClaimedCriteria(summary),
+            });
+            return {
+                status: 'claims_complete',
+                summary: summary || 'The provider returned no text for this step.',
+                satisfiedCriteria: evidence.satisfiedCriteria,
+                artifact: evidence.artifact,
+                commit: evidence.commit,
+                blockedReason: null,
+            };
+        }
+        catch (error) {
+            sessionsByRun.delete(context.runId);
+            // A refusal by the supervision boundary is not a provider failure. It
+            // says the envelope is too narrow, which no retry can change, so it gets
+            // its own status and names the tool the owner has to grant.
+            if (error instanceof RuntimeSupervisionRejectedError
+                && PERMISSION_REJECTION_CODES.has(error.rejectionCode)) {
+                return {
+                    status: 'permission_denied',
+                    summary: 'The supervision boundary refused this step.',
+                    satisfiedCriteria: [],
+                    artifact: null,
+                    commit: null,
+                    blockedReason: error.message,
+                    denial: { toolName: error.toolName, code: error.rejectionCode },
+                };
+            }
+            // Provider loss is a failure of this run, not a silent retry: the owner is
+            // told, and the Run reaches an authoritative terminal state.
+            return {
+                status: 'failed',
+                summary: 'The supervised runtime session could not complete this step.',
+                satisfiedCriteria: [],
+                artifact: null,
+                commit: null,
+                blockedReason: error instanceof Error ? error.message : 'runtime_step_failed',
+            };
+        }
+    };
+}
+//# sourceMappingURL=workGoldenPathRuntimeExecutor.js.map

package/build/server/products/work/state/workGoldenPathRuntimeExecutor.js.map

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

package/build/server/products/work/state/workGoldenPathService.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Transport work-delivery golden path (SPEC-114, ADR-112).
+ *
+ * This is the product-owned coordinator: it owns intent capture, scope
+ * versioning, authorization, completion judgment, and delivery policy, and it
+ * owns none of the transport mechanics or provider execution. The transport
+ * calls in through `TransportWorkGoldenPathPort`; the supervised run reports
+ * execution facts in and receives no authority in return.
+ *
+ * Every method here is idempotent by construction. That is not defensive
+ * programming: a Telegram callback can arrive twice, a process can restart
+ * mid-flight, and either must converge on the same Task, Run, and single
+ * outbound message.
+ */
+import type { CoreStore } from '../../../core/store.js';
+import type { CoreDeliveryGate, CoreDeliveryMode, CoreRunStatus, ExecutionTargetSummary } from '../../../core/types.js';
+import type { SupervisionToolScope } from '../../../platform/supervision/contracts.js';
+import { type TransportWorkActionTokenStore } from '../../../platform/transports/work-delivery/actionTokens.js';
+import type { TransportWorkPayloadAction, TransportWorkProposalV1, TransportWorkReadiness, TransportWorkStage } from '../../../platform/transports/work-delivery/contracts.js';
+import { type TransportWorkOutbox } from '../../../platform/transports/work-delivery/outbox.js';
+import type { TransportWorkStageProjection } from '../../../platform/transports/work-delivery/stageProjection.js';
+import { type WorkCommitEvidence, type WorkCompletionEvidenceResult } from './workCompletionEvidence.js';
+import type { RuntimeDeliveryClient } from '../../../platform/runtime/deliveryClient.js';
+import type { TransportWorkTelemetry } from '../../../platform/transports/work-delivery/telemetry.js';
+import type { WorkGoldenPathAdmissionResult } from './workGoldenPathAdmission.js';
+import { type MessageKey } from '../../../shared/i18n/index.js';
+export interface WorkGoldenPathRequestInput {
+    bindingId: string;
+    conversationId: string;
+    ownerActorId: string;
+    externalUserRef: string;
+    externalConversationRef: string;
+    externalUpdateRef: string;
+    externalMessageRef: string | null;
+    goal: string;
+    targetLabel: string;
+    projectId: string | null;
+    workspacePath: string | null;
+    acceptanceCriteria: readonly string[];
+    deliveryMode: CoreDeliveryMode;
+    deliveryGates: readonly CoreDeliveryGate[];
+    openQuestion: string | null;
+    readiness: TransportWorkReadiness;
+    /** Owner's transport locale; every later message is rendered in it. */
+    locale: string | null;
+    /** Return after durable Core/outbox capture; transport send continues safely. */
+    deferDelivery?: boolean;
+}
+export type WorkGoldenPathActionOffer = TransportWorkPayloadAction;
+export interface WorkGoldenPathRequestResult {
+    status: 'accepted' | 'not_ready';
+    workItemId: string | null;
+    proposal: TransportWorkProposalV1 | null;
+    offers: WorkGoldenPathActionOffer[];
+    readiness: TransportWorkReadiness;
+}
+export interface WorkGoldenPathAuthorizeInput {
+    callbackData: string;
+    bindingId: string;
+    externalUserRef: string;
+    /** Telegram callback query id; distinguishes owner events, not scopes. */
+    ownerEventRef: string;
+    readiness: TransportWorkReadiness;
+    executionTarget?: ExecutionTargetSummary | null;
+    toolScope?: SupervisionToolScope;
+    workspaceHeadOid?: string | null;
+    /** Return after durable admission/outbox capture; transport send continues safely. */
+    deferDelivery?: boolean;
+}
+export interface WorkGoldenPathRefusalInput {
+    bindingId: string;
+    externalConversationRef: string;
+    externalUpdateRef: string;
+    reasonKey: MessageKey;
+    locale: string | null;
+}
+export interface WorkGoldenPathAuthorizeResult {
+    status: 'admitted' | 'already_admitted' | 'rejected' | 'cancelled' | 'published' | 'publish_denied' | 'publish_blocked' | 'retried' | 'resumed';
+    /** Set when the caller should drive this Run again. */
+    redriveRunId?: string | null;
+    /** The work item the action landed on, when one was resolved. */
+    workItemId?: string | null;
+    rejection?: string;
+    admission?: WorkGoldenPathAdmissionResult;
+    stage: TransportWorkStage | null;
+}
+export interface WorkGoldenPathRunEvidence {
+    workItemId: string;
+    runId: string;
+    /** Criteria the supervised run reported satisfied, by exact proposal text. */
+    satisfiedCriteria: readonly string[];
+    summary: string;
+    /** Artifact the run produced, for `artifact_only`. */
+    artifact: {
+        title: string;
+        path: string | null;
+        mimeType: string | null;
+        deliveryWorkspacePath?: string | null;
+        deliverySessionId?: string | null;
+    } | null;
+    /** Commit evidence for every repository-backed delivery mode. */
+    commit: WorkCommitEvidence | null;
+}
+export interface WorkGoldenPathCompletionResult {
+    status: 'result_ready' | 'delivered' | 'insufficient_evidence';
+    evidence: WorkCompletionEvidenceResult;
+    stage: TransportWorkStage;
+    outstandingGates: CoreDeliveryGate[];
+    deliveredMessageRef: string | null;
+}
+/** What the transport is allowed to call. Keeps ADR-112 section 4 honest. */
+export interface TransportWorkGoldenPathPort {
+    receiveRequest(input: WorkGoldenPathRequestInput): Promise<WorkGoldenPathRequestResult>;
+    authorize(input: WorkGoldenPathAuthorizeInput): Promise<WorkGoldenPathAuthorizeResult>;
+    describeStage(workItemId: string): Promise<TransportWorkStageProjection | null>;
+}
+export interface WorkGoldenPathServiceOptions {
+    coreStore: CoreStore;
+    outbox: TransportWorkOutbox;
+    tokenStore?: TransportWorkActionTokenStore;
+    actorRef?: string;
+    /** Absent means gated publication can be approved but not performed. */
+    deliveryClient?: RuntimeDeliveryClient;
+    /** Optional counters. Absent means the path runs unmeasured, never broken. */
+    telemetry?: TransportWorkTelemetry;
+    now?: () => Date;
+}
+export interface WorkGoldenPathService extends TransportWorkGoldenPathPort {
+    markRunStatus(input: {
+        workItemId: string;
+        runId: string;
+        status: CoreRunStatus;
+        stageKey: MessageKey;
+        milestoneKey: MessageKey;
+    }): Promise<void>;
+    completeRun(input: WorkGoldenPathRunEvidence): Promise<WorkGoldenPathCompletionResult>;
+    /** Sends a bounded explanation for an input this slice cannot ingest. */
+    sendRefusal(input: WorkGoldenPathRefusalInput): Promise<void>;
+    /** Tells the owner the run stopped and needs them, with state-valid actions. */
+    notifyDecisionNeeded(input: {
+        workItemId: string;
+        runId: string;
+        reasonKey: MessageKey;
+        consequenceKey: MessageKey;
+        /** Interpolation for `reasonKey`, when it names something specific. */
+        reasonValues?: Record<string, string>;
+        discriminator: string;
+    }): Promise<void>;
+    readonly tokenStore: TransportWorkActionTokenStore;
+}
+export declare function createWorkGoldenPathService(options: WorkGoldenPathServiceOptions): WorkGoldenPathService;
+//# sourceMappingURL=workGoldenPathService.d.ts.map

package/build/server/products/work/state/workGoldenPathService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workGoldenPathService.d.ts","sourceRoot":"","sources":["../../../../../src/products/work/state/workGoldenPathService.ts"],"names":[],"mappings":"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"}