@kontourai/flow-agents 3.12.1 → 4.0.0

package/dist/codex/build/generated/capability-declarations.json

@@ -0,0 +1,177 @@
+{
+  "claude-code": {
+    "turn_id": {
+      "status": "supported"
+    },
+    "transcript_path": {
+      "status": "supported"
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "partial",
+      "note": "Captured only when the workflow records an evidence/verdict event for the sub-agent — not guaranteed every run."
+    }
+  },
+  "codex": {
+    "turn_id": {
+      "status": "supported"
+    },
+    "transcript_path": {
+      "status": "supported"
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "Codex does not surface a per-sub-agent terminal verdict to the orchestrator."
+    }
+  },
+  "kiro": {
+    "turn_id": {
+      "status": "supported"
+    },
+    "transcript_path": {
+      "status": "supported"
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "partial",
+      "note": "Captured only when the workflow records an evidence/verdict event for the sub-agent — not guaranteed every run."
+    }
+  },
+  "opencode": {
+    "turn_id": {
+      "status": "partial",
+      "note": "session.start telemetry is unavailable in opencode run (non-interactive) mode; tool events still carry a turn context."
+    },
+    "transcript_path": {
+      "status": "unsupported",
+      "reason": "opencode does not expose a per-session transcript path to hooks."
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "opencode does not surface per-sub-agent terminal verdicts."
+    }
+  },
+  "pi": {
+    "turn_id": {
+      "status": "supported"
+    },
+    "transcript_path": {
+      "status": "unsupported",
+      "reason": "pi does not expose a per-session transcript path to hooks."
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "pi has no named-subagent registry, so per-sub-agent verdicts are not observable."
+    }
+  },
+  "codex-local": {
+    "turn_id": {
+      "status": "unsupported",
+      "reason": "codex-local is a kit-activation adapter, not an agent-runtime telemetry source; it emits no per-turn agent-runtime telemetry."
+    },
+    "transcript_path": {
+      "status": "unsupported",
+      "reason": "codex-local is a kit-activation adapter and does not expose a per-session transcript path."
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "codex-local is a kit-activation adapter and does not surface per-sub-agent terminal verdicts."
+    }
+  },
+  "strands-local": {
+    "turn_id": {
+      "status": "unsupported",
+      "reason": "strands-local is a kit-activation adapter, not an agent-runtime telemetry source; it emits no per-turn agent-runtime telemetry."
+    },
+    "transcript_path": {
+      "status": "unsupported",
+      "reason": "strands-local is a kit-activation adapter and does not expose a per-session transcript path."
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "strands-local is a kit-activation adapter and does not surface per-sub-agent terminal verdicts."
+    }
+  }
+}

package/dist/codex/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.12.1",
+  "version": "4.0.0",
   "type": "module"
 }

package/dist/codex/build/src/builder-flow-runtime.d.ts

@@ -1,4 +1,5 @@
 import { type GateActionEnvelope, type GateActionProgressSnapshot } from "./builder-gate-action-envelope.js";
+import { type BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 import { type BuilderFlowId, type BuilderFlowRunResult } from "./builder-flow-run-adapter.js";
 type AnyRecord = Record<string, any>;
 export interface BuilderFlowSessionInput {
@@ -32,6 +33,42 @@ export declare function cancelBuilderFlowSession(input: BuilderFlowAuthorizedLif
     assignmentReleased: boolean;
     idempotent: boolean;
 }>;
+export interface BuilderCancelRequestInput extends BuilderFlowSessionInput {
+    /** Free-text reason recorded in the authorization request. */
+    reason?: string;
+    /** Human/operator identity recorded as request.authority.actor. */
+    requestActor?: string;
+    /** Validity window for the emitted authorization (default 24h). */
+    expiresInHours?: number;
+    /** Override the request timestamp (tests); defaults to now. */
+    now?: string;
+    /** Override the nonce (tests); defaults to a fresh unique value. */
+    nonce?: string;
+}
+export interface BuilderCancelRequestResult {
+    runId: string;
+    subject: string;
+    runStatus: string;
+    /** True when the run is already terminal (cancel would be idempotent/no-op). */
+    alreadyTerminal: boolean;
+    /** The unsigned, ready-to-sign authorization (schema-valid, canonical order). */
+    authorization: Omit<BuilderLifecycleAuthorization, "signature">;
+    /** The exact bytes the operator must sign; a signature over these verifies. */
+    signingPayload: string;
+    /** Where the CLI writes the unsigned authorization by default. */
+    suggestedOutFile: string;
+}
+/**
+ * Generate a ready-to-sign cancel authorization for a run (#659 Slice C).
+ *
+ * READ-ONLY: this mints the *unsigned* payload (correct run identity, active
+ * assignment holder, fresh nonce/expiry) so an operator no longer has to
+ * hand-assemble the JSON. It does NOT sign, cancel, or mutate anything — the
+ * ed25519 signature lock is fully preserved; the operator still signs
+ * `signingPayload` with their key, and `builder-run cancel --authorization-file`
+ * verifies it as before.
+ */
+export declare function prepareBuilderCancelRequest(input: BuilderCancelRequestInput): Promise<BuilderCancelRequestResult>;
 export declare function releaseBuilderFlowAssignment(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult & {
     assignmentReleased: boolean;
 }>;

package/dist/codex/build/src/builder-flow-runtime.js

@@ -7,7 +7,7 @@ import { flowAgentsPackageVersion } from "./lib/package-version.js";
 import { pinnedFlowAgentsCommand } from "./lib/pinned-cli-command.js";
 import { deriveBuilderGateActionEnvelope, deriveBuilderGateActionProgressSnapshot } from "./builder-gate-action-envelope.js";
 import { evaluateGate, expectationsForGate, lifecycleRequestMatches, openGates, } from "@kontourai/flow";
-import { assertAuthorizationUnused, loadBuilderLifecycleAuthorization, readAuthorizationConsumption, recordAuthorizationConsumed } from "./builder-lifecycle-authority.js";
+import { assertAuthorizationUnused, buildUnsignedLifecycleAuthorization, loadBuilderLifecycleAuthorization, readAuthorizationConsumption, recordAuthorizationConsumed } from "./builder-lifecycle-authority.js";
 import { assignmentFilePath, performLocalReleaseUnderLock, readLocalAssignmentStatus, resolveCurrentAssignmentActor, withSubjectLock } from "./cli/assignment-provider.js";
 import { BUILDER_BUILD_FLOW_ID, BuilderBuildRunInputError, cancelBuilderFlowRun, evaluateBuilderFlowRun, loadBuilderFlowRun, pauseBuilderFlowRun, resumeBuilderFlowRun, startBuilderFlowRun, } from "./builder-flow-run-adapter.js";
 export async function startBuilderFlowSession(input) {
@@ -113,6 +113,76 @@ export async function cancelBuilderFlowSession(input) {
         return { sessionDir: prepared.context.sessionDir, projectRoot: prepared.context.projectRoot, run: changed, projection, gateActionEnvelope, progressSnapshot, attached: false, assignmentReleased: released !== null, idempotent: changed.idempotent };
     });
 }
+/**
+ * Generate a ready-to-sign cancel authorization for a run (#659 Slice C).
+ *
+ * READ-ONLY: this mints the *unsigned* payload (correct run identity, active
+ * assignment holder, fresh nonce/expiry) so an operator no longer has to
+ * hand-assemble the JSON. It does NOT sign, cancel, or mutate anything — the
+ * ed25519 signature lock is fully preserved; the operator still signs
+ * `signingPayload` with their key, and `builder-run cancel --authorization-file`
+ * verifies it as before.
+ */
+export async function prepareBuilderCancelRequest(input) {
+    const context = resolveSessionContext(input.sessionDir);
+    const sidecarSnapshot = readSidecarSnapshot(context);
+    const subject = workflowSubject(sidecarSnapshot.state);
+    const canonicalRun = await loadBuilderFlowRun({ cwd: context.projectRoot, runId: context.slug });
+    const terminalStatuses = ["canceled", "completed", "archived"];
+    const alreadyTerminal = terminalStatuses.includes(canonicalRun.state.status);
+    const activeAssignment = readLocalAssignmentStatus(context.artifactRoot, context.slug).record;
+    const assignmentFile = assignmentFilePath(context.artifactRoot, context.slug);
+    const persistedAssignment = pathExistsNoFollow(assignmentFile)
+        ? JSON.parse(fs.readFileSync(assignmentFile, "utf8"))
+        : null;
+    // When the run is already canceled, its assignment is released — accept the
+    // persisted holder so an operator can still mint a (recovery) authorization.
+    // Mirror prepareAuthorizedLifecycleChange's redemption gate EXACTLY so we never
+    // mint an authorization the real cancel would reject: a cancel may reuse a
+    // released assignment only when the run is already `canceled` (idempotent
+    // recovery) and the persisted record's status is `released`. A completed or
+    // archived run with no active holder is not cancel-redeemable, so refuse.
+    const acceptsReleasedAssignment = canonicalRun.state.status === "canceled";
+    const assignment = activeAssignment
+        ?? (acceptsReleasedAssignment && persistedAssignment?.status === "released" ? persistedAssignment : null);
+    if (!assignment || !assignment.actor_key || !assignment.actor) {
+        throw new BuilderBuildRunInputError("assignment", "the run has no assignment holder to authorize a cancel against");
+    }
+    const now = input.now ? new Date(input.now) : new Date();
+    if (!Number.isFinite(now.getTime()))
+        throw new BuilderBuildRunInputError("now", "must be a valid date-time");
+    const requestedAt = now.toISOString();
+    const hours = input.expiresInHours && input.expiresInHours > 0 ? input.expiresInHours : 24;
+    const expiresAt = new Date(now.getTime() + hours * 3_600_000).toISOString();
+    const nonce = input.nonce ?? `cancel-request-${context.slug}-${now.getTime()}-${randomBytes(6).toString("hex")}`;
+    const { unsigned, signingPayload } = buildUnsignedLifecycleAuthorization({
+        operation: "cancel",
+        run_id: context.slug,
+        subject,
+        assignment_actor_key: assignment.actor_key,
+        assignment_actor: assignment.actor,
+        nonce,
+        expires_at: expiresAt,
+        request: {
+            reason: (input.reason && input.reason.trim()) || `Operator-requested cancellation of run ${context.slug}.`,
+            authority: {
+                kind: "user_request",
+                actor: (input.requestActor && input.requestActor.trim()) || "operator",
+                request_ref: `flow-agents://cancel-request/${context.slug}/${now.getTime()}`,
+                requested_at: requestedAt,
+            },
+        },
+    });
+    return {
+        runId: context.slug,
+        subject,
+        runStatus: canonicalRun.state.status,
+        alreadyTerminal,
+        authorization: unsigned,
+        signingPayload,
+        suggestedOutFile: path.join(context.sessionDir, "cancel.authorization.unsigned.json"),
+    };
+}
 export async function releaseBuilderFlowAssignment(input) {
     const context = resolveSessionContext(input.sessionDir);
     return await withSubjectLock(context.artifactRoot, context.slug, async () => {

package/dist/codex/build/src/builder-gate-action-envelope.d.ts

@@ -5,12 +5,43 @@ export type GateActionInterfaceParameter = {
     name: string;
     flag: string;
     required: boolean;
-    allowed_values?: string[];
+    allowed_values?: readonly string[];
     repeatable?: boolean;
     required_when?: {
         parameter: string;
         equals: string;
     };
+    value_schema_ref?: "#/public_interfaces/schemas/evidence_ref_json";
+};
+export type GateActionArtifactTarget = {
+    kind: "file";
+    ref: string;
+    path: string;
+    direct_write_allowed: true;
+    produced_via: {
+        interface: "skill";
+        skill_ids: string[];
+    };
+} | {
+    kind: "file";
+    ref: string;
+    path: string;
+    direct_write_allowed: false;
+    produced_via: {
+        interface: "operation";
+        operations: string[];
+    };
+} | {
+    kind: "trust_slice";
+    ref: string;
+    bundle_file: "trust.bundle";
+    slice_id: string;
+    direct_write_allowed: false;
+    record_via: Array<"workflow.evidence" | "workflow.critique">;
+};
+export type GateActionArtifactBinding = {
+    target: GateActionArtifactTarget;
+    expectation_ids: string[];
 };
 export type GateActionWorkflowMutation = {
     expectation_id: string;
@@ -21,7 +52,7 @@ export type GateActionWorkflowMutation = {
     };
     command: "flow-agents";
     argv: string[];
-    parameters: GateActionInterfaceParameter[];
+    parameters: readonly GateActionInterfaceParameter[];
 };
 export type GateActionPublicMutation = GateActionWorkflowMutation | {
     expectation_id: string;
@@ -35,7 +66,7 @@ export type GateActionPublicMutation = GateActionWorkflowMutation | {
     };
 };
 export type GateActionEnvelope = {
-    schema_version: "2.0";
+    schema_version: "3.0";
     flow: {
         run_id: string;
         definition_id: string;
@@ -72,13 +103,22 @@ export type GateActionEnvelope = {
             sha256: string;
         }>;
         operations: string[];
-        declared_artifacts: string[];
+        declared_artifacts: GateActionArtifactTarget[];
+        artifact_bindings: GateActionArtifactBinding[];
         declared_evidence: string[];
         implementation_allowed: boolean;
     };
     public_interfaces: {
         status: {
-            command: string;
+            package: {
+                name: "@kontourai/flow-agents";
+                version: string;
+            };
+            command: "flow-agents";
+            argv: string[];
+        };
+        schemas: {
+            evidence_ref_json: AnyRecord;
         };
         mutations: GateActionPublicMutation[];
     };
@@ -92,7 +132,7 @@ export type GateActionEnvelope = {
         };
         required: {
             skill_ids: string[];
-            artifact_refs: string[];
+            artifact_refs: GateActionArtifactTarget[];
             unresolved_evidence_ids: string[];
         };
         sequence: ["activate_required_skills", "produce_declared_artifacts", "record_bound_evidence", "synchronize_canonical_flow", "return_adapter_result"];
@@ -112,6 +152,7 @@ export type GateActionEnvelope = {
         prior_turn?: GateActionPriorProgress;
     };
 };
+export { EVIDENCE_REF_JSON_SCHEMA } from "./cli/public-contracts.js";
 export type GateActionProgressSnapshot = Pick<GateActionEnvelope["progress"], "canonical_evidence" | "observed_artifacts"> & {
     current_step: string;
     /** Optional for compatibility with snapshots persisted before terminal status capture. */
@@ -138,6 +179,17 @@ export type BuilderGateActionEnvelopeInput = {
     };
     definition: AnyRecord;
 };
+export declare function installedBuilderSkillIdentity(skill: string): GateActionEnvelope["action"]["skills"][number];
+export declare function installedBuilderImplementationAllowed(definitionId: string, currentStep: string): boolean;
+export declare function installedBuilderGateActionAuthority(definitionId: string, currentStep: string, runId: string): {
+    definition_version: string;
+    gate_id: string;
+    requirements: Array<Omit<GateActionEnvelope["gate"]["requirements"][number], "status">>;
+    action: GateActionEnvelope["action"];
+    mutations: GateActionPublicMutation[];
+    artifact_bindings: GateActionArtifactBinding[];
+    external_capability?: NonNullable<GateActionEnvelope["stop_condition"]["external_capability"]>;
+};
 /** Derive bounded adapter context without trusting adapter telemetry. */
 export declare function deriveBuilderGateActionEnvelope(input: BuilderGateActionEnvelopeInput): GateActionEnvelope;
 /**
@@ -149,4 +201,3 @@ export declare function deriveBuilderGateActionProgressSnapshot(input: BuilderGa
 export declare function gateActionProgressSnapshot(envelope: GateActionEnvelope): GateActionProgressSnapshot;
 export declare function withGateActionPriorProgress(envelope: GateActionEnvelope, priorTurn: GateActionPriorProgress): GateActionEnvelope;
 export declare function observeBuilderArtifactsForProgress(sessionDir: string, artifacts: string[]): string[];
-export {};