@tea-agent/loop-agent 0.16.26 → 0.17.0

package/dist/shared/operator/capabilities.js

@@ -0,0 +1,255 @@
+import { OPERATOR_ERROR_CODES_V1, OPERATOR_OUTCOMES_V1 } from "./registry.js";
+/** Shared constants so dag + dagSpecVersions cannot diverge. */
+const DAG_SPEC_SUPPORTED_PARSE = [1, 2, 3, 4];
+const DAG_SPEC_NEW_WRITER_DEFAULT = 4;
+const DAG_SPEC_HISTORICAL_TERMINAL_READ_ONLY = [1, 2, 3];
+const TASK_CONTRACT_BINDING_SCHEMA_VERSION = 1;
+const REQUIRES_TASK_CONTRACT_BINDING = true;
+const COMMON_MUTATION_ERRORS = [
+    "INVALID_INPUT",
+    "REQUEST_ID_REUSE_CONFLICT",
+    "REVISION_CONFLICT",
+    "OBSERVED_HASH_CONFLICT",
+    "LEASE_HELD",
+    "TRANSACTION_INCOMPLETE",
+    "NOT_FOUND",
+];
+export function buildOperatorCapabilitiesDocument() {
+    const actions = [
+        {
+            action: "operatorCapabilities",
+            cli: "loop-agent operator capabilities --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["UNSUPPORTED_SCHEMA_VERSION", "INVALID_INPUT"],
+            description: "Publish action/schema/error registry for Console negotiation.",
+        },
+        {
+            action: "contractShow",
+            cli: "loop-agent task contract show <taskId> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Return TaskContractStateV1 + observed hashes.",
+        },
+        {
+            action: "contractValidate",
+            cli: "loop-agent task contract validate --task <id> --input <path> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND", "PATH_OUTSIDE_REPO"],
+            description: "Schema/path/traceability validation for a Draft (read-only).",
+        },
+        {
+            action: "contractDiff",
+            cli: "loop-agent task contract diff --task <id> --input <path> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND", "PATH_OUTSIDE_REPO"],
+            description: "Risk-classified diff against current managed/legacy state.",
+        },
+        {
+            action: "contractApply",
+            cli: "loop-agent task contract apply --task <id> --input <path> --expected-revision <n> --expected-observed-hash <sha256> --request-id <id> --request-payload-sha256 <sha256> --json",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "EXTERNALLY_MODIFIED"],
+            description: "Journaled apply of Draft to canonical task facts.",
+        },
+        {
+            action: "newTask",
+            cli: "loop-agent new-task <id> <title> --json",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [...COMMON_MUTATION_ERRORS],
+            description: "Create a new task harness skeleton via sibling CLI.",
+        },
+        {
+            action: "importPrd",
+            cli: "loop-agent import-prd <id> --file <server-staged-path> --json",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "PATH_OUTSIDE_REPO"],
+            description: "Import immutable PRD/source reference via sibling CLI (server-staged file).",
+        },
+        {
+            action: "sourceInstructions",
+            cli: "loop-agent instructions source --task <id> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Read source instruction contract for a task.",
+        },
+        {
+            action: "contractDraftSave",
+            cli: "console application-data draft save (non-canonical)",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT"],
+            description: "Save TaskContractDraftV1 to Console application data only (not repo .harness).",
+        },
+        {
+            action: "prepareDagConfirmation",
+            cli: "console aggregate confirmation receipt (server-side)",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [
+                "INVALID_INPUT",
+                "BINDING_DRIFT",
+                "HUMAN_CONFIRMATION_REQUIRED",
+            ],
+            description: "Prepare server-side DagConfirmationV1 receipt for human challenge.",
+        },
+        {
+            action: "confirmDagConfirmation",
+            cli: "console aggregate confirmation human challenge (server-side)",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [
+                "INVALID_INPUT",
+                "NOT_FOUND",
+                "CONFIRMATION_STALE",
+                "CONFIRMATION_EXPIRED",
+                "CONFIRMATION_CONSUMED",
+                "HUMAN_CONFIRMATION_REQUIRED",
+            ],
+            description: "Human challenge confirm of DagConfirmationV1 using server-derived current bindings.",
+        },
+        {
+            action: "observeLink",
+            cli: "console observe deep-link builder (read-only navigation)",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT"],
+            description: "Build Observe deep link from stable object identity.",
+        },
+        {
+            action: "inspect",
+            cli: "loop-agent inspect --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT"],
+            description: "Repo preflight (registry entry; envelope migration follow-up).",
+        },
+        {
+            action: "doctor",
+            cli: "loop-agent doctor --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "OPERATION_NEEDS_RECONCILE"],
+            description: "Repo doctor (registry entry; envelope migration follow-up).",
+        },
+        {
+            action: "status",
+            cli: "loop-agent status <taskId> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Task status (registry entry).",
+        },
+        {
+            action: "spineCheck",
+            cli: "loop-agent spine audit <taskId> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Spine audit (registry entry).",
+        },
+        {
+            action: "dagRunTask",
+            cli: "loop-agent dag run-task <taskId> --profile auto",
+            kind: "long-running",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [
+                "NOT_MANAGED",
+                "BINDING_DRIFT",
+                "EXTERNALLY_MODIFIED",
+                "INVALID_INPUT",
+            ],
+            description: "Generate DagSpec v4 with taskContractBinding (managed required).",
+        },
+        {
+            action: "dagValidate",
+            cli: "loop-agent dag validate --dag <path> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "BINDING_DRIFT"],
+            description: "Validate DAG including taskContractBinding drift checks.",
+        },
+        {
+            action: "runDag",
+            cli: "loop-agent run-dag --dag <path>",
+            kind: "long-running",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [
+                "BINDING_DRIFT",
+                "CONTROLLER_MISMATCH",
+                "INVALID_INPUT",
+            ],
+            description: "Execute reviewed DAG; revalidate binding before writer start.",
+        },
+    ];
+    return {
+        schemaVersion: 1,
+        envelopeSchemaVersion: 1,
+        outcomes: OPERATOR_OUTCOMES_V1,
+        errorCodes: OPERATOR_ERROR_CODES_V1,
+        dagSpecVersions: {
+            supportedParse: DAG_SPEC_SUPPORTED_PARSE,
+            newWriterDefault: DAG_SPEC_NEW_WRITER_DEFAULT,
+            historicalTerminalReadOnly: DAG_SPEC_HISTORICAL_TERMINAL_READ_ONLY,
+        },
+        dag: {
+            supportedSpecVersions: DAG_SPEC_SUPPORTED_PARSE,
+            generatedSpecVersion: DAG_SPEC_NEW_WRITER_DEFAULT,
+            requiresTaskContractBinding: REQUIRES_TASK_CONTRACT_BINDING,
+            taskContractBindingSchemaVersion: TASK_CONTRACT_BINDING_SCHEMA_VERSION,
+        },
+        taskContract: {
+            draftSchemaVersion: 1,
+            refSchemaVersion: 1,
+            projectionVersion: 1,
+            canonicalizerVersion: 1,
+            taskConfigSchemaVersion: 1,
+        },
+        actions,
+    };
+}

package/dist/shared/operator/envelope.js

@@ -0,0 +1,59 @@
+export function buildOperatorResult(input) {
+    const envelope = {
+        schemaVersion: 1,
+        command: input.command,
+        ok: input.ok,
+        outcome: input.outcome,
+        warnings: input.warnings ?? [],
+    };
+    if (input.result !== undefined) {
+        envelope.result = input.result;
+    }
+    if (input.error !== undefined) {
+        envelope.error = input.error;
+    }
+    return envelope;
+}
+export function operatorSucceeded(command, result, warnings = []) {
+    return buildOperatorResult({
+        command,
+        ok: true,
+        outcome: "succeeded",
+        result,
+        warnings,
+    });
+}
+export function operatorFailed(input) {
+    return buildOperatorResult({
+        command: input.command,
+        ok: false,
+        outcome: input.outcome,
+        warnings: input.warnings ?? [],
+        error: {
+            code: input.code,
+            message: input.message,
+            ...(input.details ? { details: input.details } : {}),
+        },
+    });
+}
+/** Write a single complete JSON document to stdout (never JSONL). */
+export function writeOperatorJson(result) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+export function processExitCodeForOutcome(outcome) {
+    switch (outcome) {
+        case "succeeded":
+            return 0;
+        case "not-found":
+            return 2;
+        case "invalid":
+        case "rejected":
+        case "conflict":
+        case "blocked":
+        case "timed-out":
+        case "needs-reconcile":
+            return 1;
+        default:
+            return 1;
+    }
+}

package/dist/shared/operator/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./envelope.js";
+export * from "./capabilities.js";

package/dist/shared/operator/registry.js

@@ -0,0 +1,38 @@
+export const OPERATOR_OUTCOMES_V1 = [
+    "succeeded",
+    "rejected",
+    "conflict",
+    "blocked",
+    "not-found",
+    "invalid",
+    "timed-out",
+    "needs-reconcile",
+];
+export const OPERATOR_ERROR_CODES_V1 = [
+    "UNSUPPORTED_SCHEMA_VERSION",
+    "CAPABILITY_MISMATCH",
+    "INVALID_INPUT",
+    "PATH_OUTSIDE_REPO",
+    "REQUEST_ID_REUSE_CONFLICT",
+    "REVISION_CONFLICT",
+    "OBSERVED_HASH_CONFLICT",
+    "LEASE_HELD",
+    "TRANSACTION_INCOMPLETE",
+    "BINDING_DRIFT",
+    "CONTROLLER_MISMATCH",
+    "HUMAN_CONFIRMATION_REQUIRED",
+    "OPERATION_NEEDS_RECONCILE",
+    "EVENT_CURSOR_EXPIRED",
+    "NOT_FOUND",
+    "NOT_MANAGED",
+    "EXTERNALLY_MODIFIED",
+    "INTERNAL_ERROR",
+    "PI_SETUP_REQUIRED",
+    "CONFIRMATION_EXPIRED",
+    "CONFIRMATION_STALE",
+    "CONFIRMATION_CONSUMED",
+];
+export const OPERATOR_ERROR_CODE_SET = new Set(OPERATOR_ERROR_CODES_V1);
+export function isOperatorErrorCode(code) {
+    return OPERATOR_ERROR_CODE_SET.has(code);
+}

package/dist/shared/operator/types.js

@@ -0,0 +1,5 @@
+/**
+ * Operator machine envelope types (design §5.1).
+ * Physical path: src/shared/operator (allowed via src/shared/**).
+ */
+export {};

package/dist/task/contract/adopt.js

@@ -0,0 +1,166 @@
+import { CANONICALIZER_VERSION, PROJECTION_VERSION, TASK_CONFIG_SCHEMA_VERSION, TASK_CONTRACT_REF_SCHEMA_VERSION, } from "./constants.js";
+import { ContractMutationError } from "./apply.js";
+import { computeCanonicalHash, computeSourceHashes, computeTaskConfigSha256, } from "./hash.js";
+import { acquireTaskContractLock, assertLockHeld } from "./lock.js";
+import { loadObservedTaskBytes, logicalRevisionForState, observeTaskContractState, readStoredContractRef, } from "./observe.js";
+import { serializeTaskConfigForDisk } from "./project.js";
+import { appendRequestLedgerEntry, findRequestLedgerEntry, } from "./request-ledger.js";
+import { finalizeTransaction, runJournaledContractCommit, } from "./transaction.js";
+import { getTaskPaths, parseTaskConfigForRuntime } from "../runtime.js";
+/**
+ * Adopt current on-disk 需求.md / 执行约束.md / task.json as next managed revision.
+ * Does not rewrite reference bytes. Requires deterministic readable facts.
+ */
+export async function adoptTaskContract(input) {
+    const existing = await findRequestLedgerEntry({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+        requestId: input.requestId,
+    });
+    if (existing) {
+        if (existing.requestPayloadSha256 !== input.requestPayloadSha256) {
+            throw new ContractMutationError("REQUEST_ID_REUSE_CONFLICT", `requestId ${input.requestId} was used with a different payload hash`);
+        }
+        const ref = await readStoredContractRef(getTaskPaths(input.repoRoot, input.taskId).contractPath);
+        if (!ref) {
+            throw new ContractMutationError("OPERATION_NEEDS_RECONCILE", "request ledger hit but contract.json missing");
+        }
+        return {
+            ref,
+            changedFiles: [],
+            idempotentReplay: true,
+            txId: existing.txId,
+        };
+    }
+    const lock = await acquireTaskContractLock({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+        requestId: input.requestId,
+        operation: "contract-adopt",
+    });
+    try {
+        const existingUnderLock = await findRequestLedgerEntry({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            requestId: input.requestId,
+        });
+        if (existingUnderLock) {
+            if (existingUnderLock.requestPayloadSha256 !== input.requestPayloadSha256) {
+                throw new ContractMutationError("REQUEST_ID_REUSE_CONFLICT", `requestId ${input.requestId} was used with a different payload hash`);
+            }
+            const ref = await readStoredContractRef(getTaskPaths(input.repoRoot, input.taskId).contractPath);
+            if (!ref) {
+                throw new ContractMutationError("OPERATION_NEEDS_RECONCILE", "request ledger hit but contract.json missing");
+            }
+            return {
+                ref,
+                changedFiles: [],
+                idempotentReplay: true,
+                txId: existingUnderLock.txId,
+            };
+        }
+        const state = await observeTaskContractState(input.repoRoot, input.taskId);
+        if (state.effectiveStatus === "transaction-incomplete") {
+            throw new ContractMutationError("TRANSACTION_INCOMPLETE", "unfinished transaction; run task contract recover first");
+        }
+        const currentRevision = logicalRevisionForState(state);
+        if (input.expectedRevision !== currentRevision) {
+            throw new ContractMutationError("REVISION_CONFLICT", `expectedRevision ${input.expectedRevision} does not match current ${currentRevision}`, { currentRevision, expectedRevision: input.expectedRevision });
+        }
+        const bytes = await loadObservedTaskBytes(input.repoRoot, input.taskId);
+        if (bytes.requirementBytes === null ||
+            bytes.constraintsBytes === null ||
+            bytes.taskConfigRaw === null ||
+            bytes.taskConfigSha256 === null) {
+            throw new ContractMutationError("INVALID_INPUT", "adopt requires existing 需求.md, 执行约束.md, and task.json");
+        }
+        const observedHash = state.observedCanonicalHash;
+        if (!observedHash) {
+            throw new ContractMutationError("OBSERVED_HASH_CONFLICT", "unable to observe current canonical hash for adopt");
+        }
+        if (input.expectedObservedHash !== observedHash) {
+            throw new ContractMutationError("OBSERVED_HASH_CONFLICT", "expectedObservedHash does not match current observed hash", {
+                expectedObservedHash: input.expectedObservedHash,
+                observedCanonicalHash: observedHash,
+            });
+        }
+        const fullConfig = parseTaskConfigForRuntime(bytes.taskConfigRaw);
+        const taskConfigContent = serializeTaskConfigForDisk(fullConfig);
+        const sourceHashes = computeSourceHashes({
+            requirementBytes: bytes.requirementBytes,
+            constraintsBytes: bytes.constraintsBytes,
+            referenceManifestBytes: bytes.referenceManifestBytes,
+        });
+        const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
+        const canonicalHash = computeCanonicalHash({
+            sourceHashes,
+            taskConfigSha256,
+        });
+        // Sanity: observed should equal recomputed
+        if (canonicalHash !== observedHash) {
+            throw new ContractMutationError("OBSERVED_HASH_CONFLICT", "recomputed canonical hash diverged during adopt");
+        }
+        const nextRevision = currentRevision + 1;
+        const nextRef = {
+            schemaVersion: TASK_CONTRACT_REF_SCHEMA_VERSION,
+            taskId: input.taskId,
+            revision: nextRevision,
+            projectionVersion: PROJECTION_VERSION,
+            canonicalizerVersion: CANONICALIZER_VERSION,
+            taskConfigSchemaVersion: TASK_CONFIG_SCHEMA_VERSION,
+            sourceHashes,
+            taskConfigSha256,
+            canonicalHash,
+            updatedAt: new Date().toISOString(),
+            lastRequestId: input.requestId,
+        };
+        // Adopt rewrites contract.json and re-writes same source/config bytes
+        // (stable content) so journal protocol is uniform.
+        await assertLockHeld(lock);
+        const { txId, ref } = await runJournaledContractCommit({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            operation: "adopt",
+            requestId: input.requestId,
+            requestPayloadSha256: input.requestPayloadSha256,
+            expectedRevision: input.expectedRevision,
+            expectedObservedCanonicalHash: input.expectedObservedHash,
+            nextRevision,
+            fencingToken: lock.record.fencingToken,
+            targets: {
+                requirementContent: bytes.requirementBytes,
+                constraintsContent: bytes.constraintsBytes,
+                taskConfigContent,
+                contractRef: nextRef,
+            },
+        });
+        await appendRequestLedgerEntry({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            entry: {
+                schemaVersion: 1,
+                requestId: input.requestId,
+                requestPayloadSha256: input.requestPayloadSha256,
+                txId,
+                revision: ref.revision,
+                canonicalHash: ref.canonicalHash,
+                recordedAt: new Date().toISOString(),
+                resultSummary: { ok: true, operation: "adopt" },
+            },
+        });
+        await finalizeTransaction({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            txId,
+        });
+        return {
+            ref,
+            changedFiles: ["contract.json"],
+            idempotentReplay: false,
+            txId,
+        };
+    }
+    finally {
+        await lock.release();
+    }
+}