@tea-agent/loop-agent 0.41.1 → 0.42.0-next.10

package/dist/shared/context-transfer/artifact-revision.js

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import { artifactRevisionV1Schema } from "../context-transfer.js";
+import { redactSecretsWithFindings } from "../preview.js";
+export const ARTIFACT_REVISION_LIMITS = Object.freeze({
+    singleFileBytes: 10 * 1024 * 1024,
+    diffPreviewBytes: 64 * 1024,
+});
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function isTextMedia(mediaType) {
+    return mediaType.startsWith("text/") || mediaType.includes("json") || mediaType.includes("xml");
+}
+function stableJson(bytes) {
+    try {
+        const value = JSON.parse(bytes.toString("utf8"));
+        const sort = (input) => {
+            if (Array.isArray(input))
+                return input.map(sort);
+            if (input && typeof input === "object") {
+                return Object.fromEntries(Object.entries(input)
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([key, child]) => [key, sort(child)]));
+            }
+            return input;
+        };
+        return `${JSON.stringify(sort(value), null, 2)}\n`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function boundedLineDiff(before, after) {
+    const beforeLines = before.split(/\r?\n/);
+    const afterLines = after.split(/\r?\n/);
+    const rows = [];
+    const limit = Math.max(beforeLines.length, afterLines.length);
+    for (let index = 0; index < limit; index += 1) {
+        if (beforeLines[index] === afterLines[index])
+            continue;
+        if (beforeLines[index] !== undefined)
+            rows.push(`- ${beforeLines[index]}`);
+        if (afterLines[index] !== undefined)
+            rows.push(`+ ${afterLines[index]}`);
+    }
+    const complete = rows.join("\n");
+    const preview = Buffer.from(complete, "utf8");
+    if (preview.byteLength <= ARTIFACT_REVISION_LIMITS.diffPreviewBytes) {
+        return { summary: complete, truncated: false };
+    }
+    return {
+        summary: preview.subarray(0, ARTIFACT_REVISION_LIMITS.diffPreviewBytes).toString("utf8") + "\n[diff truncated]",
+        truncated: true,
+    };
+}
+export function validateAndDescribeArtifactRevision(input) {
+    if (input.declaration.revisionPolicy !== "replace-file") {
+        throw new Error("ARTIFACT_NOT_REVISION_ELIGIBLE");
+    }
+    if (input.candidateBytes.byteLength > ARTIFACT_REVISION_LIMITS.singleFileBytes) {
+        throw new Error("ARTIFACT_REVISION_SCHEMA_INVALID: candidate exceeds size limit");
+    }
+    if (sha256(input.parentBytes) !== input.parentSha256) {
+        throw new Error("ARTIFACT_REVISION_DRIFT: parent artifact hash mismatch");
+    }
+    if (input.mediaType !== input.declaration.mediaType) {
+        throw new Error("ARTIFACT_REVISION_SCHEMA_INVALID: media type mismatch");
+    }
+    const textCandidate = isTextMedia(input.mediaType);
+    if (textCandidate &&
+        redactSecretsWithFindings(input.candidateBytes.toString("utf8"))
+            .findingCount > 0) {
+        throw new Error("SECRET_SCAN_CONFIRMATION_REQUIRED");
+    }
+    const candidateSha256 = sha256(input.candidateBytes);
+    if (candidateSha256 === input.parentSha256) {
+        throw new Error("ARTIFACT_REVISION_SCHEMA_INVALID: replacement is unchanged");
+    }
+    let kind = "binary";
+    let summary = `binary ${input.parentBytes.byteLength} -> ${input.candidateBytes.byteLength} bytes; ${input.parentSha256} -> ${candidateSha256}`;
+    let truncated = false;
+    let diffPreview;
+    const schemaChecks = [];
+    if (input.declaration.schemaId || input.mediaType.includes("json")) {
+        const before = stableJson(input.parentBytes);
+        const after = stableJson(input.candidateBytes);
+        if (!before || !after) {
+            throw new Error("ARTIFACT_REVISION_SCHEMA_INVALID: expected valid JSON");
+        }
+        kind = "json";
+        const declaredSchemaId = input.declaration.schemaId;
+        if (declaredSchemaId) {
+            const validator = input.artifactSchemaResolver?.(declaredSchemaId);
+            if (!validator) {
+                // Fail closed (W4.3): a declared schema without a registered
+                // validator must not pass as "JSON syntax only" — revision
+                // eligibility would silently outrun actual verification.
+                throw new Error(`ARTIFACT_REVISION_SCHEMA_INVALID: no registered revision validator for ${declaredSchemaId}; artifact cannot be staged until its schema is registered`);
+            }
+            const parsed = JSON.parse(after);
+            const result = validator.safeParse(parsed);
+            if (!result.success) {
+                const issue = result.error.issues[0];
+                const issuePath = issue
+                    ? issue.path.map((part) => String(part)).join(".")
+                    : "(root)";
+                throw new Error(`ARTIFACT_REVISION_SCHEMA_INVALID: candidate does not satisfy ${declaredSchemaId} at ${issuePath}: ${issue?.message ?? "schema violation"}`);
+            }
+            schemaChecks.push({
+                id: "artifact-schema",
+                status: "pass",
+                detail: declaredSchemaId,
+            });
+        }
+        const diff = boundedLineDiff(before, after);
+        summary = diff.summary;
+        truncated = diff.truncated;
+        diffPreview = Buffer.from(diff.summary, "utf8");
+    }
+    else if (isTextMedia(input.mediaType)) {
+        kind = "text";
+        const diff = boundedLineDiff(input.parentBytes.toString("utf8"), input.candidateBytes.toString("utf8"));
+        summary = diff.summary;
+        truncated = diff.truncated;
+        diffPreview = Buffer.from(diff.summary, "utf8");
+    }
+    const revision = artifactRevisionV1Schema.parse({
+        schemaVersion: 1,
+        revisionId: input.revisionId,
+        state: "validated",
+        parent: {
+            runId: input.parentRunId,
+            nodeId: input.producerNodeId,
+            artifactPath: input.declaration.path,
+            artifactSha256: input.parentSha256,
+            ...(input.declaration.schemaId ? { artifactSchemaId: input.declaration.schemaId } : {}),
+        },
+        candidate: {
+            stagingPath: input.stagingPath,
+            sha256: candidateSha256,
+            bytes: input.candidateBytes.byteLength,
+            mediaType: input.mediaType,
+            uploadedAt: input.uploadedAt,
+            uploadedBy: "operator",
+        },
+        validation: {
+            status: "pass",
+            checks: [
+                { id: "parent-hash", status: "pass" },
+                { id: "declared-path", status: "pass" },
+                { id: "media-type", status: "pass" },
+                textCandidate
+                    ? { id: "secret-scan", status: "pass" }
+                    : {
+                        id: "secret-scan",
+                        status: "warning",
+                        detail: "binary candidate was not decoded for text secret scanning",
+                    },
+                ...(kind === "json" ? [{ id: "json-syntax", status: "pass" }] : []),
+                ...schemaChecks,
+            ],
+        },
+        diff: {
+            kind,
+            summary,
+            ...(diffPreview ? { previewPath: `artifact-revisions/${input.revisionId}/diff.txt` } : {}),
+            truncated,
+        },
+        expiresAt: input.expiresAt,
+    });
+    return { revision, ...(diffPreview ? { diffPreview } : {}) };
+}

package/dist/shared/context-transfer.js

@@ -0,0 +1,418 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const CONTEXT_TRANSFER_REASON_CODES = [
+    "CONTEXT_RECEIPT_MISSING",
+    "CONTEXT_COMPONENT_UNAVAILABLE",
+    "CONTEXT_BUNDLE_INEXACT",
+    "CONTEXT_BUNDLE_TOO_LARGE",
+    "RAW_EXPORT_ACKNOWLEDGEMENT_REQUIRED",
+    "SECRET_SCAN_CONFIRMATION_REQUIRED",
+    "ARTIFACT_BINDING_UNAVAILABLE",
+    "ARTIFACT_NOT_REVISION_ELIGIBLE",
+    "ARTIFACT_IDENTITY_AMBIGUOUS",
+    "ARTIFACT_REVISION_SCHEMA_INVALID",
+    "ARTIFACT_REVISION_PATH_INVALID",
+    "ARTIFACT_REVISION_EXPIRED",
+    "ARTIFACT_REVISION_DRIFT",
+    "ARTIFACT_REVISION_QUOTA_EXCEEDED",
+    "ARTIFACT_CONSUMER_UNKNOWN",
+    "ARTIFACT_IMPACT_UNSAFE",
+    "RERUN_PLAN_DRIFT",
+    "WORKER_MANAGED_CONTINUATION_UNSUPPORTED",
+    "WORKER_CONTINUATION_AUTHORITY_MISMATCH",
+    "WORKER_CONTINUATION_NEEDS_RECONCILE",
+];
+export const contextTransferReasonCodeSchema = z.enum(CONTEXT_TRANSFER_REASON_CODES);
+export const CONTEXT_BUNDLE_LIMITS = Object.freeze({
+    previewBytes: 64 * 1024,
+    singleFileBytes: 16 * 1024 * 1024,
+    totalUncompressedBytes: 64 * 1024 * 1024,
+    fileCount: 2_048,
+});
+const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+const safeRelativePosixPathSchema = z
+    .string()
+    .min(1)
+    .refine((value) => !value.includes("\0"), "path must not contain NUL")
+    .refine((value) => !value.includes("\\"), "path must use POSIX separators")
+    .refine((value) => !value.startsWith("/") &&
+    !value.startsWith("//") &&
+    !/^[A-Za-z]:/.test(value), "path must be relative")
+    .refine((value) => value.split("/").every((segment) => segment !== ".." && segment !== ""), "path must not escape or contain empty segments");
+const contextComponentSchema = z
+    .object({
+    index: z.number().int().nonnegative(),
+    kind: z.enum([
+        "system-prompt",
+        "developer-prompt",
+        "user-prompt",
+        "task-contract",
+        "execution-constraint",
+        "context-file",
+        "upstream-artifact",
+        "tool-contract",
+        "runtime-fact",
+    ]),
+    logicalName: z.string().min(1),
+    source: z
+        .object({
+        type: z.string().min(1),
+        identity: z.string().min(1),
+        revision: z.string().min(1).optional(),
+    })
+        .strict(),
+    materializedPath: safeRelativePosixPathSchema.optional(),
+    sha256: sha256Schema,
+    bytes: z.number().int().nonnegative(),
+    mediaType: z.string().min(1),
+    inclusion: z.enum([
+        "full",
+        "excerpt",
+        "summary",
+        "reference-only",
+        "omitted",
+    ]),
+    authoritativeSource: z
+        .object({ identity: z.string().min(1), sha256: sha256Schema.optional() })
+        .strict()
+        .optional(),
+    omissionReason: z.string().min(1).optional(),
+})
+    .strict();
+export const effectiveNodeContextV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    identity: z
+        .object({
+        runId: z.string().min(1),
+        nodeId: z.string().min(1),
+        attempt: z.number().int().positive(),
+        capturedAt: z.string().min(1),
+    })
+        .strict(),
+    orderedComponents: z.array(contextComponentSchema),
+    promptAssembly: z
+        .object({
+        strategy: z.string().min(1),
+        finalPromptSha256: sha256Schema.optional(),
+        tokenEstimate: z.number().int().nonnegative().optional(),
+        truncations: z.array(z
+            .object({
+            componentIndex: z.number().int().nonnegative(),
+            reason: z.string().min(1),
+            retainedBytes: z.number().int().nonnegative().optional(),
+        })
+            .strict()),
+    })
+        .strict(),
+    boundaries: z
+        .object({
+        allowedPaths: z.array(z.string()),
+        forbiddenPaths: z.array(z.string()),
+        writeSet: z.array(z.string()),
+    })
+        .strict(),
+    runtime: z
+        .object({
+        executor: z.string().min(1),
+        modelHint: z.string().min(1).optional(),
+        resolvedModel: z.string().min(1).optional(),
+        skills: z.array(z.string()),
+        extensions: z.array(z.string()),
+        activeTools: z.array(z.string()),
+    })
+        .strict(),
+    contextDigest: sha256Schema,
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    value.orderedComponents.forEach((component, index) => {
+        if (component.index !== index) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["orderedComponents", index, "index"],
+                message: "component indexes must be contiguous and ordered",
+            });
+        }
+    });
+});
+const bundleFileSchema = z
+    .object({
+    path: safeRelativePosixPathSchema,
+    sha256: sha256Schema,
+    bytes: z.number().int().nonnegative(),
+    mediaType: z.string().min(1),
+    origin: z.string().min(1),
+    redaction: z.enum(["none", "redacted", "omitted"]),
+    sourceSha256: sha256Schema.optional(),
+})
+    .strict();
+export const contextBundleManifestV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    bundleId: z.string().min(1),
+    createdAt: z.string().min(1),
+    source: z
+        .object({
+        repoIdentity: z.string().min(1),
+        taskId: z.string().min(1).optional(),
+        runId: z.string().min(1),
+        nodeId: z.string().min(1),
+        attempt: z.number().int().positive(),
+        pass: z.number().int().positive().optional(),
+        parentRunId: z.string().min(1).optional(),
+    })
+        .strict(),
+    profile: z.enum(["redacted", "raw"]),
+    target: z.enum(["generic", "pi-session", "pi-handoff", "readable"]),
+    reproducibility: z
+        .object({
+        level: z.enum([
+            "exact-pi-session",
+            "semantic-handoff",
+            "readable-transcript",
+        ]),
+        reasons: z.array(z.string()),
+        limitations: z.array(z.string()),
+    })
+        .strict(),
+    bindings: z
+        .object({
+        frozenRunSpecSha256: sha256Schema,
+        contextReceiptSha256: sha256Schema,
+        contextDigest: sha256Schema,
+        taskContractSha256: sha256Schema.optional(),
+        sourceBindingSha256: sha256Schema.optional(),
+    })
+        .strict(),
+    runtime: z
+        .object({
+        executor: z.string().min(1),
+        model: z.string().min(1).optional(),
+        provider: z.string().min(1).optional(),
+        piVersion: z.string().min(1).optional(),
+        skills: z.array(z
+            .object({
+            id: z.string().min(1),
+            version: z.string().min(1).optional(),
+            sha256: sha256Schema.optional(),
+        })
+            .strict()),
+        extensions: z.array(z
+            .object({
+            id: z.string().min(1),
+            packageName: z.string().min(1).optional(),
+            version: z.string().min(1).optional(),
+            status: z.string().min(1),
+        })
+            .strict()),
+        tools: z.array(z
+            .object({
+            name: z.string().min(1),
+            contractSha256: sha256Schema.optional(),
+            available: z.boolean(),
+        })
+            .strict()),
+    })
+        .strict(),
+    files: z.array(bundleFileSchema),
+    omissions: z.array(z
+        .object({
+        subject: z.string().min(1),
+        reasonCode: z.string().min(1),
+        detail: z.string().min(1).optional(),
+    })
+        .strict()),
+    security: z
+        .object({
+        secretScan: z.enum(["pass", "warning", "not-run"]),
+        findingCounts: z.record(z.string(), z.number().int().nonnegative()),
+        rawAcknowledgement: z
+            .object({
+            requestId: z.string().min(1),
+            acknowledgedAt: z.string().min(1),
+        })
+            .strict()
+            .optional(),
+    })
+        .strict(),
+    bundleSha256: sha256Schema,
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const seen = new Set();
+    for (const [index, file] of value.files.entries()) {
+        const folded = file.path.normalize("NFC").toLocaleLowerCase("en-US");
+        if (seen.has(folded)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["files", index, "path"],
+                message: "bundle file paths must be unique under case folding",
+            });
+        }
+        seen.add(folded);
+    }
+    if (value.profile === "raw" && !value.security.rawAcknowledgement) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["security", "rawAcknowledgement"],
+            message: "raw bundle requires explicit acknowledgement",
+        });
+    }
+});
+export const artifactRevisionV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    revisionId: z.string().min(1),
+    state: z.enum([
+        "staged",
+        "validated",
+        "rejected",
+        "expired",
+        "consumed",
+        "discarded",
+    ]),
+    parent: z
+        .object({
+        runId: z.string().min(1),
+        nodeId: z.string().min(1),
+        artifactPath: safeRelativePosixPathSchema,
+        artifactSha256: sha256Schema,
+        artifactSchemaId: z.string().min(1).optional(),
+    })
+        .strict(),
+    candidate: z
+        .object({
+        stagingPath: z.string().min(1),
+        sha256: sha256Schema,
+        bytes: z.number().int().nonnegative(),
+        mediaType: z.string().min(1),
+        uploadedAt: z.string().min(1),
+        uploadedBy: z.literal("operator"),
+    })
+        .strict(),
+    validation: z
+        .object({
+        status: z.enum(["pending", "pass", "fail"]),
+        checks: z.array(z
+            .object({
+            id: z.string().min(1),
+            status: z.enum(["pass", "warning", "fail"]),
+            detail: z.string().min(1).optional(),
+        })
+            .strict()),
+    })
+        .strict(),
+    diff: z
+        .object({
+        kind: z.enum(["text", "json", "binary"]),
+        summary: z.string(),
+        previewPath: safeRelativePosixPathSchema.optional(),
+        truncated: z.boolean(),
+    })
+        .strict(),
+    expiresAt: z.string().min(1),
+    /** Explicit staging lease (M4c): fresh lease blocks conflicting holders. */
+    lease: z
+        .object({
+        holder: z.string().min(1),
+        acquiredAt: z.string().min(1),
+        expiresAt: z.string().min(1),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+export const artifactOverrideSetV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    overrides: z
+        .array(z
+        .object({
+        revisionId: z.string().min(1),
+        parentArtifact: z
+            .object({
+            runId: z.string().min(1),
+            nodeId: z.string().min(1),
+            path: safeRelativePosixPathSchema,
+            sha256: sha256Schema,
+        })
+            .strict(),
+        replacement: z
+            .object({
+            sha256: sha256Schema,
+            bytes: z.number().int().nonnegative(),
+            mediaType: z.string().min(1),
+        })
+            .strict(),
+        supersedes: z.string().min(1),
+    })
+        .strict())
+        .length(1),
+    overrideSetHash: sha256Schema,
+})
+    .strict();
+const workerContinuationIdSchema = z
+    .string()
+    .min(1)
+    .regex(/^[A-Za-z0-9._-]+$/);
+/**
+ * Console-to-kernel authority for a Worker-owned artifact continuation.
+ * Every field is immutable and plan-hash-bound; the child identity is derived
+ * from the parent Worker run plus the single-use revision id.
+ */
+export const workerContinuationAuthorityV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    parentWorkerRunId: workerContinuationIdSchema,
+    childWorkerRunId: workerContinuationIdSchema,
+    featureId: workerContinuationIdSchema,
+    taskId: workerContinuationIdSchema,
+    batchRunId: workerContinuationIdSchema,
+    revisionId: workerContinuationIdSchema,
+})
+    .strict()
+    .superRefine((authority, ctx) => {
+    const expected = deriveWorkerContinuationRunId(authority.parentWorkerRunId, authority.revisionId);
+    if (authority.childWorkerRunId !== expected) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["childWorkerRunId"],
+            message: `childWorkerRunId must equal ${expected}`,
+        });
+    }
+});
+export function deriveWorkerContinuationRunId(parentWorkerRunId, revisionId) {
+    const digest = createHash("sha256")
+        .update(`worker-continuation-v1\0${parentWorkerRunId}\0${revisionId}`)
+        .digest("hex")
+        .slice(0, 32);
+    return `wrc-${digest}`;
+}
+export function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, child]) => [key, sortKeysDeep(child)]));
+    }
+    return value;
+}
+export function canonicalSha256(value) {
+    return createHash("sha256")
+        .update(JSON.stringify(sortKeysDeep(value)))
+        .digest("hex");
+}
+export function computeContextDigest(context) {
+    return canonicalSha256(context);
+}
+export function computeBundleManifestSha256(manifest) {
+    return canonicalSha256(manifest);
+}
+export function computeOverrideSetHash(overrides) {
+    return canonicalSha256({ schemaVersion: 1, overrides });
+}
+export function isKnownContextTransferReasonCode(value) {
+    return contextTransferReasonCodeSchema.safeParse(value).success;
+}

package/dist/shared/dag-failure-category.js

@@ -47,10 +47,22 @@ const RAW_TO_NORMALIZED = {
     "verify-failure": "validation",
     "test-failure": "validation",
     "verification-plan-stale": "validation",
+    "read-burst": "validation",
+    // Writer persisted real file changes but the final provider call hit a
+    // context overflow; verification never ran. Distinct from empty-output so
+    // the report shows partial success instead of a spec issue.
+    "partial-success-with-context-overflow": "validation",
+    // Writer burned an excessive token budget (unconverged read-edit-test loop)
+    // and still failed; distinct from empty-output for accurate reporting.
+    "writer-budget-exhausted": "validation",
     network: "executor",
     quota: "executor",
     "rate-limit": "executor",
     unavailable: "executor",
+    // Context window overflow (400 request-too-large): the session needs
+    // compaction / fresh context before retrying — an executor-side
+    // environment condition, not a plan-quality defect.
+    "context-overflow": "executor",
     // Deterministic capability/policy refusal: missing verified launcher JS
     // entry, capability allowlist rejection, or missing bounded write tool
     // profile. These are environment/config defects the operator repairs