@kontourai/flow-agents 3.11.0 → 3.12.1

package/dist/claude-code/build/src/builder-gate-action-envelope.js

@@ -0,0 +1,368 @@
+import * as fs from "node:fs";
+import { constants as fsConstants } from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { evaluateGate, expectationsForGate, openGates } from "@kontourai/flow";
+import { parseKitFlowStepActions } from "./flow-kit/validate.js";
+import { PUBLIC_OPERATION_CONTRACTS, WORKFLOW_CRITIQUE_STATUSES } from "./cli/public-contracts.js";
+import { flowAgentsPackageRoot } from "./lib/package-version.js";
+import { pinnedFlowAgentsCommand } from "./lib/pinned-cli-command.js";
+const MAX_METADATA_BYTES = 1_048_576;
+const MAX_ENVELOPE_BYTES = 65_536;
+const MAX_SKILLS = 16;
+const MAX_REQUIREMENTS = 32;
+const MAX_ARTIFACTS = 32;
+const MAX_CANONICAL_EVIDENCE = 256;
+const MAX_OBSERVED_ARTIFACTS = 128;
+const MAX_OBSERVED_ARTIFACT_BYTES = 8 * 1_048_576;
+const CONTROL_ARTIFACTS = new Set(["state.json"]);
+/** Derive bounded adapter context without trusting adapter telemetry. */
+export function deriveBuilderGateActionEnvelope(input) {
+    const loaded = loadGateAction(input);
+    const derived = deriveFlowRequirements(input, loaded.action);
+    const envelope = assembleGateActionEnvelope(input, loaded, derived);
+    assertBoundedEnvelope(envelope);
+    return envelope;
+}
+/**
+ * Canonical progress is useful after a run becomes terminal, when no adapter
+ * action envelope may be emitted. Keep this deliberately separate from the
+ * request-only envelope so terminal snapshots cannot be mistaken for work.
+ */
+export function deriveBuilderGateActionProgressSnapshot(input) {
+    const { actions } = loadGateAction(input);
+    return {
+        current_step: input.run.state.current_step,
+        canonical_status: input.run.state.status,
+        canonical_evidence: canonicalEvidence(input.run.manifest),
+        observed_artifacts: observeBuilderArtifactsForProgress(input.sessionDir, actions.flatMap((entry) => entry.artifacts)),
+    };
+}
+function loadGateAction(input) {
+    const packageRoot = flowAgentsPackageRoot();
+    const packageMetadata = readBoundedJson(packageRoot, "package.json", "flow-agents package metadata");
+    if (typeof packageMetadata.version !== "string" || !packageMetadata.version)
+        throw new Error("flow-agents package metadata has no version");
+    const packageVersion = packageMetadata.version;
+    const kit = readBoundedJson(packageRoot, path.join("kits", "builder", "kit.json"), "Builder kit metadata");
+    const parsed = parseKitFlowStepActions(kit, "kits/builder/kit.json");
+    if (parsed.errors.length)
+        throw new Error(`Builder gate-action metadata is invalid: ${parsed.errors.join("; ")}`);
+    const actions = parsed.entries.filter((entry) => entry.flow_id === input.run.definitionId);
+    const selected = actions.filter((entry) => entry.step_id === input.run.state.current_step);
+    if (selected.length !== 1)
+        throw new Error(`Builder gate-action metadata must declare exactly one action for ${input.run.definitionId}/${input.run.state.current_step}`);
+    const action = selected[0];
+    const actionableArtifacts = action.artifacts.filter((artifact) => !isControlArtifact(artifact));
+    if (action.skills.length > MAX_SKILLS || action.artifacts.length > MAX_ARTIFACTS) {
+        throw new Error("Builder gate-action metadata exceeds the supported envelope bound");
+    }
+    return { packageRoot, packageVersion, kit, action, actions, actionableArtifacts };
+}
+function deriveFlowRequirements(input, action) {
+    const gates = openGates(input.definition, input.run.state);
+    const acceptedExceptions = [];
+    const requirements = gates.flatMap((gate) => {
+        const outcome = evaluateGate(input.definition, input.run.state, input.run.manifest, gate.id, input.run.config);
+        if (typeof outcome.accepted_exception_id === "string") {
+            acceptedExceptions.push({ gate_id: gate.id, exception_id: outcome.accepted_exception_id });
+        }
+        const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
+            .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
+        return expectationsForGate(gate, input.run.config)
+            .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
+    });
+    if (requirements.length > MAX_REQUIREMENTS)
+        throw new Error("Builder gate-action envelope requirements exceed the supported bound");
+    if (!sameSet(action.expectation_ids, requirements.map((requirement) => requirement.id))) {
+        throw new Error(`Builder gate-action metadata evidence does not exactly match canonical Flow requirements for ${input.run.definitionId}/${input.run.state.current_step}`);
+    }
+    const unresolved = requirements.filter((requirement) => requirement.status === "unresolved").map((requirement) => requirement.id);
+    const unresolvedRequired = requirements.filter((requirement) => requirement.required && requirement.status === "unresolved").map((requirement) => requirement.id);
+    return { gates, requirements, unresolved, unresolvedRequired, acceptedExceptions };
+}
+function assembleGateActionEnvelope(input, loaded, derived) {
+    const { packageRoot, packageVersion, kit, action, actions, actionableArtifacts } = loaded;
+    const { gates, requirements, unresolved, unresolvedRequired, acceptedExceptions } = derived;
+    const sessionDir = path.resolve(input.sessionDir);
+    const sessionArgument = sessionPathForPublicCommand(input.projectRoot, sessionDir);
+    const statusCommand = pinnedFlowAgentsCommand(packageVersion, ["workflow", "status", "--session-dir", sessionArgument, "--json"]);
+    const requiredArtifacts = action.artifact_bindings
+        .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
+        .map((binding) => binding.artifact);
+    const envelope = {
+        schema_version: "2.0",
+        flow: {
+            run_id: input.run.runId,
+            definition_id: input.run.definitionId,
+            definition_version: input.run.definitionVersion,
+            status: input.run.state.status,
+            current_step: input.run.state.current_step,
+            gate_ids: gates.map((gate) => gate.id),
+        },
+        gate: { requirements, unresolved_requirement_ids: unresolved, accepted_exceptions: acceptedExceptions },
+        action: envelopeAction(action, actionableArtifacts, kit, packageRoot, packageVersion),
+        public_interfaces: {
+            status: { command: statusCommand },
+            mutations: action.expectation_bindings.map((binding) => publicMutation(binding, sessionArgument, packageVersion)),
+        },
+        stop_condition: envelopeStopCondition(input, gates, action, requiredArtifacts, unresolvedRequired),
+        progress: {
+            canonical_evidence: canonicalEvidence(input.run.manifest),
+            observed_artifacts: observeBuilderArtifactsForProgress(sessionDir, actions.flatMap((entry) => entry.artifacts)),
+        },
+    };
+    return envelope;
+}
+function envelopeAction(action, artifacts, kit, packageRoot, packageVersion) {
+    return {
+        skills: action.skills.map((skill) => skillIdentity(kit, packageRoot, packageVersion, skill)),
+        operations: [...action.operations],
+        declared_artifacts: [...artifacts],
+        declared_evidence: [...action.expectation_ids],
+        implementation_allowed: action.implementation_allowed,
+    };
+}
+function envelopeStopCondition(input, gates, action, artifactRefs, unresolvedEvidenceIds) {
+    const operation = action.operations[0];
+    const protocol = operation ? PUBLIC_OPERATION_CONTRACTS[operation] : undefined;
+    return {
+        kind: "one_turn",
+        scope: { run_id: input.run.runId, current_step: input.run.state.current_step, gate_ids: gates.map((gate) => gate.id), current_gate_only: true },
+        required: { skill_ids: unresolvedEvidenceIds.length > 0 ? action.skills : [], artifact_refs: artifactRefs, unresolved_evidence_ids: unresolvedEvidenceIds },
+        sequence: ["activate_required_skills", "produce_declared_artifacts", "record_bound_evidence", "synchronize_canonical_flow", "return_adapter_result"],
+        after: "return_adapter_result",
+        synchronize_canonical_flow: true,
+        adapter_evidence_is_gate_evidence: false,
+        ...(protocol?.availability.status === "external_capability_required" ? {
+            external_capability: {
+                status: "waiting",
+                operation: protocol.operation,
+                capability: protocol.capability,
+                completion: "external_verification_required",
+            },
+        } : {}),
+    };
+}
+export function gateActionProgressSnapshot(envelope) {
+    return {
+        current_step: envelope.flow.current_step,
+        canonical_status: envelope.flow.status,
+        canonical_evidence: [...envelope.progress.canonical_evidence],
+        observed_artifacts: [...envelope.progress.observed_artifacts],
+    };
+}
+export function withGateActionPriorProgress(envelope, priorTurn) {
+    const copy = structuredClone(envelope);
+    copy.progress.prior_turn = structuredClone(priorTurn);
+    assertBoundedEnvelope(copy);
+    return copy;
+}
+function publicMutation(binding, sessionArgument, packageVersion) {
+    if (binding.interface === "operation") {
+        const operation = binding.operation;
+        const protocol = PUBLIC_OPERATION_CONTRACTS[operation];
+        if (!protocol)
+            throw new Error(`Builder gate-action operation '${operation}' has no canonical public protocol`);
+        return {
+            expectation_id: binding.expectation_id,
+            interface: "operation",
+            operation,
+            protocol: structuredClone(protocol),
+            completion: {
+                status: "external_verification_required",
+                executable_by_flow_agents: false,
+                gate_evidence_interface: null,
+            },
+        };
+    }
+    if (binding.interface === "workflow.critique") {
+        return {
+            expectation_id: binding.expectation_id,
+            interface: binding.interface,
+            package: { name: "@kontourai/flow-agents", version: packageVersion },
+            command: "flow-agents",
+            argv: ["workflow", "critique", "--session-dir", sessionArgument, "--json"],
+            parameters: [
+                { name: "id", flag: "--id", required: false },
+                { name: "verdict", flag: "--verdict", required: true, allowed_values: [...WORKFLOW_CRITIQUE_STATUSES] },
+                { name: "summary", flag: "--summary", required: true },
+                { name: "lane_json", flag: "--lane-json", required: true, repeatable: true },
+                { name: "artifact_ref", flag: "--artifact-ref", required: false, repeatable: true, required_when: { parameter: "verdict", equals: "pass" } },
+                { name: "finding_json", flag: "--finding-json", required: false, repeatable: true },
+                { name: "timestamp", flag: "--timestamp", required: false },
+            ],
+        };
+    }
+    return workflowEvidenceMutation(binding.expectation_id, sessionArgument, packageVersion);
+}
+function workflowEvidenceMutation(expectationId, sessionArgument, packageVersion) {
+    return {
+        expectation_id: expectationId,
+        interface: "workflow.evidence",
+        package: { name: "@kontourai/flow-agents", version: packageVersion },
+        command: "flow-agents",
+        argv: ["workflow", "evidence", "--session-dir", sessionArgument, "--expectation", expectationId, "--json"],
+        parameters: [
+            { name: "status", flag: "--status", required: true, allowed_values: ["pass", "fail", "not_verified"] },
+            { name: "summary", flag: "--summary", required: true },
+            { name: "evidence_ref_json", flag: "--evidence-ref-json", required: true, repeatable: true },
+            { name: "route_reason", flag: "--route-reason", required: false },
+            { name: "criterion_json", flag: "--criterion-json", required: false, repeatable: true },
+            { name: "accepted_gap_reason", flag: "--accepted-gap-reason", required: false },
+            { name: "waived_by", flag: "--waived-by", required: false },
+            { name: "command", flag: "--command", required: false, repeatable: true },
+        ],
+    };
+}
+function requirementFromExpectation(gateId, expectation, satisfied, acceptedException) {
+    const record = expectation;
+    const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
+    if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
+        throw new Error("canonical Flow gate contains malformed expectation metadata");
+    }
+    return {
+        id: record.id,
+        gate_id: gateId,
+        required: record.required === true,
+        description: record.description,
+        claim_type: claim.claimType,
+        subject_type: typeof claim.subjectType === "string" ? claim.subjectType : null,
+        status: satisfied.has(record.id) ? "satisfied" : acceptedException ? "accepted_exception" : "unresolved",
+    };
+}
+function skillIdentity(kit, packageRoot, version, skill) {
+    const skills = Array.isArray(kit.skills) ? kit.skills : [];
+    const entry = skills.find((candidate) => isRecord(candidate) && candidate.id === `builder.${skill}`);
+    if (!entry || typeof entry.path !== "string")
+        throw new Error(`Builder gate-action skill '${skill}' has no installed skill source`);
+    const kitRoot = path.join(packageRoot, "kits", "builder");
+    const source = readStableRegularFile(kitRoot, entry.path, `Builder skill '${skill}'`, MAX_METADATA_BYTES);
+    if (!source)
+        throw new Error(`Builder skill '${skill}' has no installed skill source`);
+    return {
+        id: skill,
+        package: { name: "@kontourai/flow-agents", version },
+        path: path.relative(fs.realpathSync(packageRoot), source.path).split(path.sep).join("/"),
+        sha256: createHash("sha256").update(source.bytes).digest("hex"),
+    };
+}
+function canonicalEvidence(manifest) {
+    const ids = (Array.isArray(manifest.evidence) ? manifest.evidence : []).flatMap((entry) => {
+        if (!isRecord(entry) || entry.superseded_by || typeof entry.gate_id !== "string")
+            return [];
+        const identity = typeof entry.sha256 === "string" ? entry.sha256 : typeof entry.id === "string" ? entry.id : null;
+        return identity ? [`${entry.gate_id}:${identity}`] : [];
+    });
+    const unique = [...new Set(ids)].sort();
+    if (unique.length > MAX_CANONICAL_EVIDENCE)
+        throw new Error("canonical Flow evidence exceeds the supported envelope bound");
+    return unique;
+}
+export function observeBuilderArtifactsForProgress(sessionDir, artifacts) {
+    const observed = [];
+    const candidates = [...new Set(artifacts)].filter((artifact) => !artifact.includes("#") && !isControlArtifact(artifact));
+    if (candidates.length > MAX_OBSERVED_ARTIFACTS)
+        throw new Error(`Builder artifact progress exceeds ${MAX_OBSERVED_ARTIFACTS} unique files`);
+    const aggregateBudget = { remaining: MAX_OBSERVED_ARTIFACT_BYTES };
+    for (const artifact of candidates) {
+        const relative = artifact.replaceAll("<slug>", path.basename(sessionDir));
+        const file = readStableRegularFile(sessionDir, relative, `Builder artifact '${artifact}'`, MAX_METADATA_BYTES, false, aggregateBudget);
+        observed.push(file
+            ? `${artifact}:${createHash("sha256").update(file.bytes).digest("hex")}`
+            : `${artifact}:absent`);
+    }
+    return observed.sort();
+}
+function isControlArtifact(artifact) {
+    return CONTROL_ARTIFACTS.has(path.posix.normalize(artifact.replaceAll("\\", "/")));
+}
+function readBoundedJson(root, candidate, label) {
+    const file = readStableRegularFile(root, candidate, label, MAX_METADATA_BYTES);
+    if (!file)
+        throw new Error(`${label} is missing`);
+    const value = JSON.parse(file.bytes.toString("utf8"));
+    if (!isRecord(value))
+        throw new Error(`${label} must be a JSON object`);
+    return value;
+}
+function readStableRegularFile(root, candidate, label, maxBytes, required = true, aggregateBudget) {
+    if (path.isAbsolute(candidate) || candidate.includes("\0"))
+        throw new Error(`${label} must be a relative path`);
+    const canonicalRoot = fs.realpathSync(root);
+    const resolved = path.resolve(canonicalRoot, candidate);
+    const relative = path.relative(canonicalRoot, resolved);
+    if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`${label} must remain within its package or session`);
+    }
+    let fd;
+    try {
+        const canonicalParentBefore = fs.realpathSync(path.dirname(resolved));
+        assertWithinRoot(canonicalRoot, canonicalParentBefore, label);
+        const parentBefore = fs.statSync(canonicalParentBefore);
+        if (!parentBefore.isDirectory())
+            throw new Error(`${label} parent must be a directory`);
+        if (typeof fsConstants.O_NOFOLLOW !== "number")
+            throw new Error(`${label} cannot be read safely because O_NOFOLLOW is unavailable`);
+        fd = fs.openSync(resolved, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        const before = fs.fstatSync(fd);
+        if (!before.isFile() || before.size > maxBytes)
+            throw new Error(`${label} must be a bounded regular file`);
+        if (aggregateBudget && before.size > aggregateBudget.remaining)
+            throw new Error(`Builder artifact progress exceeds ${MAX_OBSERVED_ARTIFACT_BYTES} aggregate bytes`);
+        if (aggregateBudget)
+            aggregateBudget.remaining -= before.size;
+        const pathBefore = fs.lstatSync(resolved);
+        if (pathBefore.isSymbolicLink() || !sameIdentity(before, pathBefore))
+            throw new Error(`${label} changed identity while opening`);
+        const bytes = fs.readFileSync(fd);
+        const after = fs.fstatSync(fd);
+        if (!sameIdentity(before, after) || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || bytes.length !== after.size) {
+            throw new Error(`${label} changed while reading`);
+        }
+        const pathAfter = fs.lstatSync(resolved);
+        if (pathAfter.isSymbolicLink() || !sameIdentity(after, pathAfter))
+            throw new Error(`${label} changed identity while reading`);
+        const canonicalParentAfter = fs.realpathSync(path.dirname(resolved));
+        const parentAfter = fs.statSync(canonicalParentAfter);
+        if (canonicalParentAfter !== canonicalParentBefore || !sameIdentity(parentBefore, parentAfter))
+            throw new Error(`${label} parent changed identity while reading`);
+        assertWithinRoot(canonicalRoot, canonicalParentAfter, label);
+        return { path: resolved, bytes };
+    }
+    catch (error) {
+        if (!required && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+function assertWithinRoot(root, candidate, label) {
+    const relative = path.relative(root, candidate);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`${label} must remain within its package or session`);
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sessionPathForPublicCommand(projectRoot, sessionDir) {
+    const relative = path.relative(path.resolve(projectRoot), sessionDir);
+    if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error("Builder session must remain within the project root for public commands");
+    }
+    return relative;
+}
+function assertBoundedEnvelope(envelope) {
+    if (Buffer.byteLength(JSON.stringify(envelope), "utf8") > MAX_ENVELOPE_BYTES)
+        throw new Error("Builder gate-action envelope exceeds 65536 bytes");
+}
+function sameSet(left, right) {
+    return left.length === right.length && new Set(left).size === left.length && left.every((entry) => right.includes(entry));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/claude-code/build/src/cli/public-contracts.d.ts

@@ -0,0 +1,139 @@
+export declare const WORKFLOW_CRITIQUE_STATUSES: readonly ["pass", "fail", "not_verified"];
+export declare const PUBLISH_CHANGE_OPERATION: "publish-change";
+export declare const PUBLISH_CHANGE_OPERATION_PROTOCOL: {
+    readonly schema_version: "1.0";
+    readonly operation: "publish-change";
+    readonly kind: "provider_capability";
+    readonly capability: "pull_request.create";
+    readonly parameters: readonly [{
+        readonly name: "title";
+        readonly required: true;
+        readonly type: "string";
+        readonly max_length: 512;
+    }, {
+        readonly name: "body";
+        readonly required: true;
+        readonly type: "string";
+        readonly max_length: 65536;
+    }, {
+        readonly name: "head_ref";
+        readonly required: true;
+        readonly type: "string";
+        readonly max_length: 255;
+    }, {
+        readonly name: "base_ref";
+        readonly required: true;
+        readonly type: "string";
+        readonly max_length: 255;
+    }, {
+        readonly name: "draft";
+        readonly required: false;
+        readonly type: "boolean";
+    }];
+    readonly result: {
+        readonly required: readonly ["provider", "repository", "number", "url", "head_ref", "base_ref"];
+        readonly properties: {
+            readonly provider: {
+                readonly type: "string";
+                readonly max_length: 128;
+            };
+            readonly repository: {
+                readonly type: "string";
+                readonly max_length: 1024;
+            };
+            readonly number: {
+                readonly type: "integer";
+                readonly minimum: 1;
+            };
+            readonly url: {
+                readonly type: "string";
+                readonly max_length: 8192;
+            };
+            readonly head_ref: {
+                readonly type: "string";
+                readonly max_length: 255;
+            };
+            readonly base_ref: {
+                readonly type: "string";
+                readonly max_length: 255;
+            };
+        };
+        readonly url_protocols: readonly ["https:"];
+        readonly persist_as: "publish-change.result.json";
+    };
+    readonly availability: {
+        readonly status: "external_capability_required";
+        readonly executable_by_flow_agents: false;
+        readonly completion_verification: "authenticated_change_provider_required";
+    };
+};
+export declare const PUBLIC_OPERATION_CONTRACTS: {
+    readonly "publish-change": {
+        readonly schema_version: "1.0";
+        readonly operation: "publish-change";
+        readonly kind: "provider_capability";
+        readonly capability: "pull_request.create";
+        readonly parameters: readonly [{
+            readonly name: "title";
+            readonly required: true;
+            readonly type: "string";
+            readonly max_length: 512;
+        }, {
+            readonly name: "body";
+            readonly required: true;
+            readonly type: "string";
+            readonly max_length: 65536;
+        }, {
+            readonly name: "head_ref";
+            readonly required: true;
+            readonly type: "string";
+            readonly max_length: 255;
+        }, {
+            readonly name: "base_ref";
+            readonly required: true;
+            readonly type: "string";
+            readonly max_length: 255;
+        }, {
+            readonly name: "draft";
+            readonly required: false;
+            readonly type: "boolean";
+        }];
+        readonly result: {
+            readonly required: readonly ["provider", "repository", "number", "url", "head_ref", "base_ref"];
+            readonly properties: {
+                readonly provider: {
+                    readonly type: "string";
+                    readonly max_length: 128;
+                };
+                readonly repository: {
+                    readonly type: "string";
+                    readonly max_length: 1024;
+                };
+                readonly number: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                };
+                readonly url: {
+                    readonly type: "string";
+                    readonly max_length: 8192;
+                };
+                readonly head_ref: {
+                    readonly type: "string";
+                    readonly max_length: 255;
+                };
+                readonly base_ref: {
+                    readonly type: "string";
+                    readonly max_length: 255;
+                };
+            };
+            readonly url_protocols: readonly ["https:"];
+            readonly persist_as: "publish-change.result.json";
+        };
+        readonly availability: {
+            readonly status: "external_capability_required";
+            readonly executable_by_flow_agents: false;
+            readonly completion_verification: "authenticated_change_provider_required";
+        };
+    };
+};
+export declare const PUBLIC_OPERATION_IDS: Set<string>;

package/dist/claude-code/build/src/cli/public-contracts.js

@@ -0,0 +1,37 @@
+export const WORKFLOW_CRITIQUE_STATUSES = ["pass", "fail", "not_verified"];
+export const PUBLISH_CHANGE_OPERATION = "publish-change";
+export const PUBLISH_CHANGE_OPERATION_PROTOCOL = {
+    schema_version: "1.0",
+    operation: PUBLISH_CHANGE_OPERATION,
+    kind: "provider_capability",
+    capability: "pull_request.create",
+    parameters: [
+        { name: "title", required: true, type: "string", max_length: 512 },
+        { name: "body", required: true, type: "string", max_length: 65_536 },
+        { name: "head_ref", required: true, type: "string", max_length: 255 },
+        { name: "base_ref", required: true, type: "string", max_length: 255 },
+        { name: "draft", required: false, type: "boolean" },
+    ],
+    result: {
+        required: ["provider", "repository", "number", "url", "head_ref", "base_ref"],
+        properties: {
+            provider: { type: "string", max_length: 128 },
+            repository: { type: "string", max_length: 1_024 },
+            number: { type: "integer", minimum: 1 },
+            url: { type: "string", max_length: 8_192 },
+            head_ref: { type: "string", max_length: 255 },
+            base_ref: { type: "string", max_length: 255 },
+        },
+        url_protocols: ["https:"],
+        persist_as: "publish-change.result.json",
+    },
+    availability: {
+        status: "external_capability_required",
+        executable_by_flow_agents: false,
+        completion_verification: "authenticated_change_provider_required",
+    },
+};
+export const PUBLIC_OPERATION_CONTRACTS = {
+    [PUBLISH_CHANGE_OPERATION]: PUBLISH_CHANGE_OPERATION_PROTOCOL,
+};
+export const PUBLIC_OPERATION_IDS = new Set(Object.keys(PUBLIC_OPERATION_CONTRACTS));

package/dist/claude-code/build/src/cli/workflow-sidecar.js

@@ -14,6 +14,7 @@ import { flowAgentsPackageRoot, flowAgentsPackageVersion } from "../lib/package-
 import { pinnedFlowAgentsCommand } from "../lib/pinned-cli-command.js";
 import { runObservedCommand } from "../lib/observed-command.js";
 import { captureReviewWorkspaceSnapshot, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
+import { WORKFLOW_CRITIQUE_STATUSES } from "./public-contracts.js";
 // #291 Wave 1 Task 1.1 exports: ensure-session's ownership guard reuses the EXACT same
 // assignment ⋈ liveness join / claim / supersede logic #290 already ships for the
 // `assignment-provider` CLI, rather than reimplementing a second, parallel join (static ESM
@@ -2514,24 +2515,19 @@ function expectedGateProducer(flowId, stepId, expectationId) {
     const action = actions.find((candidate) => candidate.flow_id === flowId && candidate.step_id === stepId);
     if (!action)
         die(`record-gate-claim cannot derive a producer for unknown Flow step ${flowId}/${stepId}`);
+    const binding = Array.isArray(action.expectation_bindings)
+        ? action.expectation_bindings.find((candidate) => candidate && typeof candidate === "object" && !Array.isArray(candidate) && candidate.expectation_id === expectationId)
+        : undefined;
+    if (binding?.interface === "operation") {
+        const operation = typeof binding.operation === "string" ? binding.operation : "the declared external operation";
+        die(`record-gate-claim cannot satisfy operation-bound expectation ${expectationId}; ${operation} requires authenticated external ChangeProvider completion`);
+    }
     const skills = Array.isArray(action.skills) ? action.skills.filter((value) => typeof value === "string") : [];
     const roles = Array.isArray(manifest.skill_roles) ? manifest.skill_roles : [];
     const owners = roles.filter((role) => typeof role.skill_id === "string"
         && Array.isArray(role.step_ids) && role.step_ids.includes(stepId)
         && Array.isArray(role.expectation_ids) && role.expectation_ids.includes(expectationId)
         && skills.includes(role.skill_id.replace(/^builder\./, "")));
-    if (owners.length === 0) {
-        const operations = Array.isArray(action.operations) ? action.operations.filter((value) => typeof value === "string") : [];
-        const operationExpectations = Array.isArray(action.expectation_ids) ? action.expectation_ids : [];
-        if (operations.length === 1 && operationExpectations.includes(expectationId)) {
-            const artifacts = Array.isArray(action.artifacts) ? action.artifacts.filter((value) => typeof value === "string") : [];
-            return {
-                id: `operation:${operations[0]}`,
-                artifactPatterns: artifacts.filter((value) => !value.includes("#")),
-                selfProducedTrustSlices: artifacts.filter((value) => value.startsWith("trust.bundle#")).map((value) => value.slice("trust.bundle#".length)),
-            };
-        }
-    }
     if (owners.length !== 1)
         die(`record-gate-claim cannot derive exactly one producer for ${flowId}/${stepId}/${expectationId}`);
     const owner = owners[0];
@@ -2820,7 +2816,7 @@ function completePassingCriteria(existing, raw, observedCommands, verifiedAt) {
         return { ...expectedById.get(ids[index]), status: "pass", evidence_refs: refs, identity_version: 2, verified_at: verifiedAt };
     });
 }
-const critiqueStatuses = new Set(["pass", "fail", "not_verified"]);
+const critiqueStatuses = new Set(WORKFLOW_CRITIQUE_STATUSES);
 const safeCritiqueId = /^[a-z][a-z0-9_-]*$/;
 function normalizeCritiqueLanes(raw) {
     if (raw.length === 0)

package/dist/claude-code/build/src/cli/workflow.d.ts

@@ -1,2 +1,3 @@
 export declare const WORKFLOW_CONTRACT_VERSION = "1.0";
 export declare function main(argv: string[]): Promise<number>;
+export declare function assertAcceptedTurnEvidenceCapacity(observedTurns: Array<Record<string, unknown>>, request: Record<string, unknown>): void;