@sema-agent/server 7.141.0 → 7.143.0

package/dist/plugins/task-attachment-store.js

@@ -1,5 +1,9 @@
 import { z } from "zod";
 import { ensureIndexes } from "./ensure-index.js";
+import { createHash } from "node:crypto";
+import { attachmentKindOf, PROJECT_BUNDLE_MIME } from "../project-bundle.js";
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { isDupKeyError, retryOnDeadlock } from "./sql-errors.js";
 export const TaskAttachmentRecordSchema = z.object({
     id: z.string(),
     owner: z.string(),
@@ -36,42 +40,151 @@ function rowToRecord(r) {
         ...(r.bound_at_ms !== null && r.bound_at_ms !== undefined ? { boundAtMs: Number(r.bound_at_ms) } : {}),
     };
 }
+export function bindRowsInProcess(rows, owner, ids, sessionId, boundAtMs) {
+    const bound = [];
+    const refused = [];
+    const claimed = [];
+    for (const id of new Set(ids)) {
+        const row = rows.get(id);
+        if (row === undefined || row.owner !== owner)
+            continue;
+        if (row.sessionId !== undefined && row.sessionId !== sessionId) {
+            refused.push({ kind: "bound_elsewhere", id });
+            continue;
+        }
+        if (row.sessionId === undefined) {
+            if (attachmentKindOf(row.mime) === "project_bundle" && [...rows.values()].some((r) => r.sessionId === sessionId && attachmentKindOf(r.mime) === "project_bundle")) {
+                refused.push({ kind: "bundle_seed_fixed", id });
+                continue;
+            }
+            row.sessionId = sessionId;
+            row.boundAtMs = boundAtMs;
+            claimed.push(row);
+        }
+        bound.push(id);
+    }
+    return { outcome: { bound, refused }, claimed };
+}
+export const ATTACHMENT_BIND_HTTP_STATUS = {
+    "attachment.bound_elsewhere": 409,
+    "attachment.bundle_lane_not_isolated": 409,
+    "attachment.bundle_seed_fixed": 409,
+};
+export function attachmentBindRefusalAnswer(r) {
+    const answer = (errorCode, message, extra) => ({ status: ATTACHMENT_BIND_HTTP_STATUS[errorCode], errorCode, message, extra });
+    switch (r.kind) {
+        case "bound_elsewhere":
+            return answer("attachment.bound_elsewhere", `attachment ${r.id} is bound to another session — an attachment, once bound, stays with that session; upload the file again for this one`, { id: r.id });
+        case "bundle_lane_not_isolated":
+            return answer("attachment.bundle_lane_not_isolated", `attachment ${r.id} is a project bundle, and this run's execution lane '${r.lane}' is not an isolated sandbox — a project bundle is unpacked only inside an isolated lane (e2b / k8s / local-docker)`, { id: r.id, lane: r.lane });
+        case "bundle_seed_fixed":
+            return answer("attachment.bundle_seed_fixed", `attachment ${r.id} is a project bundle, and this session already has its seed (the earliest bound project bundle) — a session takes one project bundle`, { id: r.id });
+        default: {
+            const unreachable = r;
+            throw new Error(`unhandled attachment bind refusal: ${String(unreachable.kind)}`);
+        }
+    }
+}
+export async function listAttachmentsBySession(store, sessionId) {
+    return (await store.listBySession(sessionId)).filter((r) => attachmentKindOf(r.mime) === "attachment");
+}
+function seedRowOf(rows) {
+    return rows
+        .filter((r) => attachmentKindOf(r.mime) === "project_bundle")
+        .sort((a, b) => (a.boundAtMs ?? 0) - (b.boundAtMs ?? 0) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))[0];
+}
+export async function seedOfSession(store, sessionId) {
+    const record = seedRowOf(await store.listBySession(sessionId));
+    if (record === undefined)
+        return undefined;
+    const bytes = await store.getContent(record.owner, record.id);
+    if (!bytes)
+        return { record, broken: `the session's project bundle ${record.id} (${record.name}) has no content in the attachment store` };
+    const sha = createHash("sha256").update(bytes).digest("hex");
+    if (bytes.byteLength !== record.sizeBytes || sha !== record.sha256) {
+        return { record, broken: `the session's project bundle ${record.id} (${record.name}) does not match its upload digest (${bytes.byteLength} bytes, sha256 ${sha}; recorded ${record.sizeBytes} bytes, sha256 ${record.sha256})` };
+    }
+    return { record, bytes };
+}
 export async function bindAttachmentsForTask(opts) {
     const found = [];
+    let seedCandidate;
     for (const id of opts.ids) {
         const rec = await opts.store.get(opts.owner, id);
         if (!rec) {
             opts.onMissing(id);
             continue;
         }
+        if (rec.sessionId !== undefined && rec.sessionId !== opts.sessionId) {
+            opts.onRefused({ kind: "bound_elsewhere", id });
+            continue;
+        }
+        if (attachmentKindOf(rec.mime) === "project_bundle" && rec.sessionId !== opts.sessionId) {
+            if (!opts.lane.isolated) {
+                opts.onRefused({ kind: "bundle_lane_not_isolated", id, lane: opts.lane.word });
+                continue;
+            }
+            if (seedCandidate !== undefined) {
+                opts.onRefused({ kind: "bundle_seed_fixed", id });
+                continue;
+            }
+            seedCandidate = id;
+        }
         found.push(rec);
     }
     if (found.length === 0)
         return { notice: undefined };
-    await opts.store.bind(opts.owner, found.map((r) => r.id), opts.sessionId, opts.nowMs);
-    const all = await opts.store.listBySession(opts.sessionId);
-    const paths = materializedRelPaths(all);
-    const lines = found.map((r) => `- ${paths.get(r.id) ?? `attachments/${r.name}`} (${r.mime}, ${r.sizeBytes} bytes)`);
-    return { notice: `[attachments] ${found.length} uploaded file(s) are available in the \`attachments/\` directory of your working directory:\n${lines.join("\n")}` };
+    const groups = seedCandidate === undefined ? [found] : [found.filter((r) => r.id === seedCandidate), found.filter((r) => r.id !== seedCandidate)];
+    const bound = new Set();
+    for (const group of groups) {
+        if (group.length === 0)
+            continue;
+        const outcome = await opts.store.bind(opts.owner, group.map((r) => r.id), opts.sessionId, opts.nowMs);
+        for (const id of outcome.bound)
+            bound.add(id);
+        const refused = new Set(outcome.refused.map((r) => r.id));
+        for (const r of outcome.refused)
+            opts.onRefused(r);
+        for (const r of group)
+            if (!bound.has(r.id) && !refused.has(r.id))
+                opts.onMissing(r.id);
+    }
+    const held = found.filter((r) => bound.has(r.id));
+    const attachments = held.filter((r) => attachmentKindOf(r.mime) === "attachment");
+    if (attachments.length === 0)
+        return { notice: undefined };
+    const paths = materializedRelPaths(await listAttachmentsBySession(opts.store, opts.sessionId));
+    const lines = attachments.map((r) => `- ${paths.get(r.id) ?? `attachments/${r.name}`} (${r.mime}, ${r.sizeBytes} bytes)`);
+    return { notice: `[attachments] ${attachments.length} uploaded file(s) are available in the \`attachments/\` directory of your working directory:\n${lines.join("\n")}` };
+}
+export async function attachmentPlacementsOf(store, sessionId) {
+    const atts = await listAttachmentsBySession(store, sessionId);
+    const paths = materializedRelPaths(atts);
+    return atts.map((record) => ({ record, relPath: paths.get(record.id) }));
+}
+export async function attachmentBytesOf(store, rec) {
+    const bytes = await store.getContent(rec.owner, rec.id);
+    if (!bytes)
+        throw new Error(`attachment materialization failed: content missing for ${rec.id} (${rec.name})`);
+    return bytes;
 }
 export async function materializeAttachmentsInto(env, store, sessionId) {
-    const atts = await store.listBySession(sessionId);
-    if (atts.length === 0)
+    const placements = await attachmentPlacementsOf(store, sessionId);
+    if (placements.length === 0)
         return 0;
-    const paths = materializedRelPaths(atts);
     const mk = await env.createDir("attachments", { recursive: true });
     if (!mk.ok)
         throw new Error(`attachment materialization failed (createDir attachments/): ${String(mk.error?.message ?? "unknown")}`);
-    for (const a of atts) {
-        const bytes = await store.getContent(a.owner, a.id);
-        if (!bytes)
-            throw new Error(`attachment materialization failed: content missing for ${a.id} (${a.name})`);
-        const w = await env.writeFile(paths.get(a.id), bytes);
+    for (const p of placements) {
+        const bytes = await attachmentBytesOf(store, p.record);
+        const w = await env.writeFile(p.relPath, bytes);
         if (!w.ok)
-            throw new Error(`attachment materialization failed (write ${paths.get(a.id)}): ${String(w.error?.message ?? "unknown")}`);
+            throw new Error(`attachment materialization failed (write ${p.relPath}): ${String(w.error?.message ?? "unknown")}`);
     }
-    return atts.length;
+    return placements.length;
 }
+const SEED_KEY = "uq_att_seed";
+const SEED_KEY_EXPR = `CASE WHEN mime = '${PROJECT_BUNDLE_MIME}' THEN session_id END`;
 export async function ensureTiDBTaskAttachmentSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TASK_ATTACHMENT_TABLE} (
     id VARCHAR(64) NOT NULL,
@@ -85,15 +198,19 @@ export async function ensureTiDBTaskAttachmentSchema(pool) {
     session_id VARCHAR(190) NULL,
     created_at_ms BIGINT NOT NULL,
     bound_at_ms BIGINT NULL,
+    -- 种子键:项目包行的会话,其余行 NULL(引擎推导,没有写者);唯一 ⇒ 一只会话一只种子
+    seed_session_id VARCHAR(190) GENERATED ALWAYS AS (${SEED_KEY_EXPR}) VIRTUAL,
     PRIMARY KEY (id),
     KEY idx_att_session (session_id),
-    KEY idx_att_unbound (created_at_ms)
+    KEY idx_att_unbound (created_at_ms),
+    UNIQUE KEY ${SEED_KEY} (seed_session_id)
   ) COLLATE utf8mb4_bin`);
     await ensureIndexes((text, params) => pool.query(text, params), "mysql", TASK_ATTACHMENT_INDEXES);
 }
 export const TASK_ATTACHMENT_INDEXES = [
     { table: `${TASK_ATTACHMENT_TABLE}`, name: "idx_att_session", columns: ["session_id"] },
     { table: `${TASK_ATTACHMENT_TABLE}`, name: "idx_att_unbound", columns: ["created_at_ms"] },
+    { table: `${TASK_ATTACHMENT_TABLE}`, name: SEED_KEY, columns: ["seed_session_id"], unique: true },
 ];
 export async function ensurePgTaskAttachmentSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${TASK_ATTACHMENT_TABLE} (
@@ -107,16 +224,81 @@ export async function ensurePgTaskAttachmentSchema(q) {
     session_id VARCHAR(190) COLLATE "C",
     created_at_ms BIGINT NOT NULL,
     bound_at_ms BIGINT,
+    -- 种子键(同 MySQL 侧注)
+    seed_session_id VARCHAR(190) COLLATE "C" GENERATED ALWAYS AS (${SEED_KEY_EXPR}) STORED,
     PRIMARY KEY (id)
   )`);
     await ensureIndexes(q, "pg", TASK_ATTACHMENT_INDEXES);
 }
+async function bindOnSql(db, owner, ids, sessionId, boundAtMs) {
+    const list = [...new Set(ids)];
+    if (list.length === 0)
+        return { bound: [], refused: [] };
+    const mysql = db.dialect === "mysql";
+    const q = (mysqlSql, pgSql) => (mysql ? mysqlSql : pgSql);
+    const ownRows = (columns, of) => db.query(q(`SELECT ${columns} FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = ? AND id IN (${of.map(() => "?").join(",")})`, `SELECT ${columns} FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = $1 AND id = ANY($2::varchar[])`), mysql ? [owner, ...of] : [owner, of]);
+    const kindOf = new Map((await ownRows("id, mime", list)).rows.map((r) => [String(r.id), attachmentKindOf(String(r.mime))]));
+    const claim = (of) => retryOnDeadlock(db.dialect, () => inTransaction(db, (conn) => conn.query(q(`UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN ? ELSE bound_at_ms END, session_id = ? WHERE owner = ? AND id IN (${of.map(() => "?").join(",")}) AND (session_id IS NULL OR session_id = ?)`, `UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN $2::bigint ELSE bound_at_ms END, session_id = $1::varchar WHERE owner = $3 AND id = ANY($4::varchar[]) AND (session_id IS NULL OR session_id = $1::varchar)`), mysql ? [boundAtMs, sessionId, owner, ...of, sessionId] : [sessionId, boundAtMs, owner, of])));
+    const attachments = list.filter((id) => kindOf.get(id) === "attachment");
+    if (attachments.length > 0)
+        await claim(attachments);
+    const seedFixed = new Set();
+    for (const id of list) {
+        if (kindOf.get(id) !== "project_bundle")
+            continue;
+        try {
+            await claim([id]);
+        }
+        catch (err) {
+            if (!isSeedKeyConflict(db.dialect, err))
+                throw err;
+            seedFixed.add(id);
+        }
+    }
+    const holderOf = new Map((await ownRows("id, session_id", list)).rows.map((r) => [String(r.id), r.session_id === null || r.session_id === undefined ? undefined : String(r.session_id)]));
+    const bound = [];
+    const refused = [];
+    for (const id of list) {
+        if (seedFixed.has(id))
+            refused.push({ kind: "bundle_seed_fixed", id });
+        else if (holderOf.get(id) === sessionId)
+            bound.push(id);
+        else if (holderOf.get(id) !== undefined)
+            refused.push({ kind: "bound_elsewhere", id });
+    }
+    return { bound, refused };
+}
+async function inTransaction(db, work) {
+    const conn = await db.connect();
+    try {
+        await conn.begin();
+        const out = await work(conn);
+        await conn.commit();
+        return out;
+    }
+    catch (err) {
+        await conn.rollback().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        conn.release();
+    }
+}
+function isSeedKeyConflict(dialect, err) {
+    if (!isDupKeyError(dialect, err) || err === null || typeof err !== "object")
+        return false;
+    if (dialect === "pg")
+        return Reflect.get(err, "constraint") === SEED_KEY;
+    return new RegExp(`\\b${SEED_KEY}\\b`).test(String(Reflect.get(err, "sqlMessage") ?? Reflect.get(err, "message") ?? ""));
+}
 export class TiDBTaskAttachmentStore {
     pool;
     bytes;
+    db;
     constructor(pool, bytes) {
         this.pool = pool;
         this.bytes = bytes;
+        this.db = mysqlDriver(pool);
     }
     async put(rec) {
         await this.bytes.putBlob(rec.sha256, rec.content);
@@ -144,11 +326,8 @@ export class TiDBTaskAttachmentStore {
             }
         }
     }
-    async bind(owner, ids, sessionId, boundAtMs) {
-        if (ids.length === 0)
-            return 0;
-        const [res] = await this.pool.query(`UPDATE ${TASK_ATTACHMENT_TABLE} SET session_id = ?, bound_at_ms = ? WHERE owner = ? AND id IN (${ids.map(() => "?").join(",")})`, [sessionId, boundAtMs, owner, ...ids]);
-        return res.affectedRows ?? 0;
+    bind(owner, ids, sessionId, boundAtMs) {
+        return bindOnSql(this.db, owner, ids, sessionId, boundAtMs);
     }
     async listBySession(sessionId) {
         const [rows] = await this.pool.query(`SELECT ${COLS} FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id = ? ORDER BY created_at_ms ASC, id ASC`, [sessionId]);
@@ -229,11 +408,13 @@ export class TiDBTaskAttachmentStore {
     }
 }
 export class PgTaskAttachmentStore {
-    q;
     bytes;
-    constructor(q, bytes) {
-        this.q = q;
+    db;
+    q;
+    constructor(pool, bytes) {
         this.bytes = bytes;
+        this.db = pgDriver(pool);
+        this.q = async (text, params) => ({ rows: (await pool.query(text, params)).rows });
     }
     async put(rec) {
         await this.bytes.putBlob(rec.sha256, rec.content);
@@ -261,11 +442,8 @@ export class PgTaskAttachmentStore {
             }
         }
     }
-    async bind(owner, ids, sessionId, boundAtMs) {
-        if (ids.length === 0)
-            return 0;
-        const res = await this.q(`UPDATE ${TASK_ATTACHMENT_TABLE} SET session_id = $1, bound_at_ms = $2 WHERE owner = $3 AND id = ANY($4::varchar[]) RETURNING id`, [sessionId, boundAtMs, owner, ids]);
-        return res.rows.length;
+    bind(owner, ids, sessionId, boundAtMs) {
+        return bindOnSql(this.db, owner, ids, sessionId, boundAtMs);
     }
     async listBySession(sessionId) {
         const res = await this.q(`SELECT ${COLS} FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id = $1 ORDER BY created_at_ms ASC, id ASC`, [sessionId]);

package/dist/plugins/tool-result-store-sql.d.ts

@@ -28,7 +28,6 @@ export declare function ensureSchema(pool: PgPool | PgPoolClient): Promise<void>
 export declare function assertToolResultProvenanceSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
 }>, dialect: SqlDialect): Promise<void>;
-/** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export declare class SqlToolResultStore implements ToolResultStore {
     protected readonly db: SqlDriver;
     /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法与「为什么 SQL 店答 managed 而三方法的实现体在
@@ -73,14 +72,16 @@ export declare class SqlToolResultStore implements ToolResultStore {
         offset?: number;
         limit?: number;
     }): Promise<ToolResultSlice | undefined>;
-    /** TTL reap: delete results older than `cutoffMs`. Returns rows removed.
+    /** core `ToolResultStore.reap` (core 7.61.0 — the one age bound every backend reads): remove the results stored more than
+     *  `opts.maxAgeMs` before `now`. No bound ⇒ nothing removed; a bound that cannot be evaluated (`maxAgeMs` not a finite
+     *  number ≥ 0, `now` not a finite number) ⇒ refused, coded `config.retention_policy_invalid`, before any row is touched;
+     *  age alone decides (ownership is not consulted — the row and its owner columns go together). Returns rows removed.
      *  C6: a real DB error must NOT collapse into the same `0` a legitimate "nothing was old enough" returns —
-     *  those are different facts (query failed vs. query succeeded on an empty set) and folding them together
-     *  makes a stuck/broken reaper indistinguishable from a healthy quiet one. Matches every sibling reaper's
-     *  form (roster-store-sql.ts `reapOlderThan`, checkpoint-store-sql.ts `reapExpired`,
-     *  workflow-journal-store-sql.ts `reapExpired`): let the error propagate — the periodic-sweep call site
-     *  (boot/reapers.ts) already wraps this call in `.catch(() => undefined)` so the reap loop itself never dies. */
-    reapOlderThan(cutoffMs: number): Promise<number>;
+     *  those are different facts (query failed vs. query succeeded on an empty set). Let the error propagate — the
+     *  periodic-sweep call site (boot/reapers.ts) wraps this call in its throttled catch so the reap loop never dies. */
+    reap(now: number, opts?: {
+        maxAgeMs?: number;
+    }): Promise<number>;
     /**
      * E21 (§0.5 session delete) — purge offloaded tool results for one session. Selection is by the row's
      * **recorded provenance** (`owner_session_id`, the [ref] column `put` writes in the same statement as the

package/dist/plugins/tool-result-store-sql.js

@@ -55,6 +55,24 @@ export async function assertToolResultProvenanceSchema(query, dialect) {
             (await describeProbedTableDrift(query, dialect, ["tool_result"])));
     }
 }
+function toolResultAgeCutoff(now, opts) {
+    const refuse = (what, v) => {
+        throw Object.assign(new Error(`ToolResultStore.reap: ${what} must be a finite number${what === "maxAgeMs" ? " of milliseconds of 0 or more" : ""} (got ${typeof v === "string" ? JSON.stringify(v) : String(v)}) — a retention bound that cannot be evaluated is refused, never read as "no bound"`), {
+            code: "config.retention_policy_invalid",
+        });
+    };
+    if (opts !== undefined) {
+        for (const key of Object.keys(opts))
+            if (key !== "maxAgeMs")
+                refuse(`the bound "${key}" (only maxAgeMs is taken)`, opts[key]);
+    }
+    const maxAgeMs = opts?.maxAgeMs;
+    if (maxAgeMs !== undefined && (typeof maxAgeMs !== "number" || !Number.isFinite(maxAgeMs) || maxAgeMs < 0))
+        refuse("maxAgeMs", maxAgeMs);
+    if (typeof now !== "number" || !Number.isFinite(now))
+        refuse("now", now);
+    return maxAgeMs === undefined ? undefined : now - maxAgeMs;
+}
 export class SqlToolResultStore {
     db;
     retention;
@@ -126,8 +144,11 @@ export class SqlToolResultStore {
             return undefined;
         return { content: String(rows[0].slice ?? ""), offset, totalChars: Number(rows[0].total) };
     }
-    async reapOlderThan(cutoffMs) {
-        const { affected } = await this.db.query(this.q("DELETE FROM tool_result WHERE created_at < ?", "DELETE FROM tool_result WHERE created_at < $1"), [new Date(cutoffMs)]);
+    async reap(now, opts) {
+        const cutoff = toolResultAgeCutoff(now, opts);
+        if (cutoff === undefined)
+            return 0;
+        const { affected } = await this.db.query(this.q("DELETE FROM tool_result WHERE created_at < ?", "DELETE FROM tool_result WHERE created_at < $1"), [new Date(cutoff)]);
         return affected;
     }
     async deleteBySession(sessionId) {

package/dist/plugins/wiring-section-codec.d.ts

@@ -0,0 +1,32 @@
+/** 块引用的唯一键。 */
+export declare const WIRING_SECTION_REF_KEY = "$blob";
+/** 一只段体:摘要(`sha256:<64 hex>`)+ 段值本身(JSON 容器)。 */
+export interface WiringSectionBlob {
+    readonly digest: string;
+    readonly body: object;
+}
+/** {@link splitForStore} 的产物:要落账本的那一形 + 本帧引用到的段体(按摘要去重,首见为准)。 */
+export interface WiringSectionSplit {
+    readonly stored: unknown;
+    readonly blobs: readonly WiringSectionBlob[];
+}
+/** 装回失败的一段:段名 + 它的引用(引用值不是串时记 `<not-a-digest>`)。 */
+export interface UnresolvedWiringSection {
+    readonly section: string;
+    readonly digest: string;
+}
+/** {@link joinFromStore} 的结局:整帧,或至少一段装不回(永不交出缺段的帧)。 */
+export type WiringSectionJoin = {
+    readonly kind: "joined";
+    readonly data: unknown;
+} | {
+    readonly kind: "unresolved";
+    readonly missing: readonly UnresolvedWiringSection[];
+};
+/** 段体的店键:段体(一只 JSON 值)规范 JSON 的 sha256 全长。 */
+export declare function wiringSectionDigest(body: object): string;
+/** 写口:清单帧里 JSON 形是容器的段换成块引用(段体是那一段的 JSON 形,与原值不共享);别的型、或 `data` 不是对象 ⇒ 原样、零块。 */
+export declare function splitForStore(type: string, data: unknown): WiringSectionSplit;
+/** 读口:清单行里恰为单键 `$blob` 对象的顶层段换回段体;任一段在 `lookup` 里找不到 ⇒ `unresolved`(点名每一段)。 */
+export declare function joinFromStore(type: string, data: unknown, lookup: (digest: string) => object | undefined): WiringSectionJoin;
+//# sourceMappingURL=wiring-section-codec.d.ts.map

package/dist/plugins/wiring-section-codec.js

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { canonicalJsonStringify } from "@sema-agent/core";
+export const WIRING_SECTION_REF_KEY = "$blob";
+const WIRING_MANIFEST = "wiring_manifest";
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function wiringSectionDigest(body) {
+    return `sha256:${createHash("sha256").update(canonicalJsonStringify(body), "utf8").digest("hex")}`;
+}
+function jsonContainerOf(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const text = JSON.stringify(value);
+    if (text === undefined)
+        return undefined;
+    const body = JSON.parse(text);
+    return typeof body === "object" && body !== null ? body : undefined;
+}
+export function splitForStore(type, data) {
+    if (type !== WIRING_MANIFEST || !isRecord(data))
+        return { stored: data, blobs: [] };
+    const blobs = new Map();
+    const stored = Object.fromEntries(Object.entries(data).map(([section, value]) => {
+        const body = jsonContainerOf(value);
+        if (body === undefined)
+            return [section, value];
+        const digest = wiringSectionDigest(body);
+        if (!blobs.has(digest))
+            blobs.set(digest, body);
+        return [section, { [WIRING_SECTION_REF_KEY]: digest }];
+    }));
+    return { stored, blobs: [...blobs].map(([digest, body]) => ({ digest, body })) };
+}
+export function joinFromStore(type, data, lookup) {
+    if (type !== WIRING_MANIFEST || !isRecord(data))
+        return { kind: "joined", data };
+    let refs = 0;
+    const missing = [];
+    const entries = Object.entries(data).map(([section, value]) => {
+        if (!isRecord(value))
+            return [section, value];
+        const keys = Object.keys(value);
+        if (keys.length !== 1 || keys[0] !== WIRING_SECTION_REF_KEY)
+            return [section, value];
+        refs += 1;
+        const ref = value[WIRING_SECTION_REF_KEY];
+        const body = typeof ref === "string" ? lookup(ref) : undefined;
+        if (body === undefined)
+            missing.push({ section, digest: typeof ref === "string" ? ref : "<not-a-digest>" });
+        return [section, body ?? value];
+    });
+    if (missing.length > 0)
+        return { kind: "unresolved", missing };
+    return { kind: "joined", data: refs === 0 ? data : Object.fromEntries(entries) };
+}
+//# sourceMappingURL=wiring-section-codec.js.map

package/dist/plugins/workspace-fill.d.ts

@@ -0,0 +1,60 @@
+import { RemoteExecutionError, type ExecutionEnvFactoryContext } from "@sema-agent/core";
+import type { Logger } from "../observability/logger.js";
+import { type TaskAttachmentStore } from "./task-attachment-store.js";
+/** 车道一次固定命令的读数(适配器自己的起动身份 —— 与引擎命令同一个执行用户;从不抛)。 */
+export type ChannelRun = {
+    readonly ok: true;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** 车道一次写的读数(建或覆盖;从不抛)。 */
+export type ChannelWrite = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * 恢复点手里那条**已经连上的**通道(不是公开的 `ExecutionEnv` 面)。两件原语,身份都是这只工作区里跑引擎命令的那个执行用户:
+ *  · `run` —— 一条固定 shell 命令(适配器的起动形);
+ *  · `write` —— 把整份字节写到一个绝对路径(父目录由调用方先建)。
+ */
+export interface WorkspaceChannel {
+    run(command: string): Promise<ChannelRun>;
+    write(absPath: string, bytes: Uint8Array): Promise<ChannelWrite>;
+}
+/** 恢复点交出的工作区从哪来:`minted` = 车道刚铸出的新工作区(没有可恢复的树 —— 含恢复点指的归档不在:`latest` 悬空、停驻快照的归档不在);`restored` = 恢复出来的(空间 `latest` / 停驻快照的树真回来了)。 */
+export type WorkspaceOrigin = "minted" | "restored";
+/** 一次填充的结局。`standing` = 这只执行环境此后每一次恢复点都会得到同一个答(适配器把它记成这只环境的拒,不再建机器)。 */
+export type FillOutcome = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly error: RemoteExecutionError;
+    readonly standing: boolean;
+};
+/** 恢复点的填充座(按 run 由工厂装配交给适配器;适配器只在恢复点调它、只说工作区从哪来,不判内容)。 */
+export interface WorkspaceFill {
+    /** 往恢复点即将交出的工作区(根 = `root`,适配器的工作根;来处 = `origin`)里放内容。 */
+    fill(channel: WorkspaceChannel, root: string, origin: WorkspaceOrigin): Promise<FillOutcome>;
+}
+/** 工厂装配按 run 取填充座的那一只读法(`boot/execution-env.ts` 铸;隔离车道的三只工厂各收它一份)。`undefined` ⇒ 这条 run 不放任何东西。 */
+export type WorkspaceFillOf = (ctx: ExecutionEnvFactoryContext) => WorkspaceFill | undefined;
+/**
+ * 一条 run 的填充座(活对象 ⇒ `create*`):会话 `sessionId` 的种子(`seeds` 为真且工作区是铸出的)与绑定的附件。
+ * 附件按物化路径(与 objective 告知同一份推导)写进 `<root>/attachments/`,每一次恢复点都整份重写(同路径同字节)。
+ */
+export declare function createWorkspaceFill(seat: {
+    readonly store: TaskAttachmentStore;
+    readonly sessionId: string;
+    /** 这条 run 是不是它工作区的空间属主(`placementRootSessionId === sessionId`):只有属主播种。 */
+    readonly seeds: boolean;
+    readonly logger?: Pick<Logger, "info">;
+}): WorkspaceFill;
+/** 播种的固定命令:建工作根(与附件的 `mkdir -p` 同姿)→ 查 `tar` → 查顶层名撞车 → 解(不还原属主)→ 不论结局都删两只临时档。 */
+export declare function seedCommand(root: string, archive: string, names: string): string;
+//# sourceMappingURL=workspace-fill.d.ts.map

package/dist/plugins/workspace-fill.js

@@ -0,0 +1,106 @@
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { RemoteExecutionError } from "@sema-agent/core";
+import { readProjectBundle } from "../project-bundle.js";
+import { attachmentBytesOf, attachmentPlacementsOf, seedOfSession } from "./task-attachment-store.js";
+import { shellQuote } from "./remote-shell.js";
+const FILLED = { ok: true };
+function refused(message, standing = false) {
+    return { ok: false, error: new RemoteExecutionError("connect_failed", message), standing };
+}
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+const SEED_NO_TAR_EXIT = 71;
+const SEED_COLLISION_EXIT = 72;
+const SEED_COLLISION_MARK = "SEMA_SEED_COLLISION ";
+export function createWorkspaceFill(seat) {
+    return {
+        async fill(channel, root, origin) {
+            if (origin === "minted" && seat.seeds) {
+                const seeded = await seedInto(channel, root, seat);
+                if (!seeded.ok)
+                    return seeded;
+            }
+            let placements;
+            try {
+                placements = await attachmentPlacementsOf(seat.store, seat.sessionId);
+            }
+            catch (e) {
+                return refused(`attachment materialization failed (listing the session's attachments): ${errText(e)}`);
+            }
+            if (placements.length === 0)
+                return FILLED;
+            const mk = await channel.run(`mkdir -p ${shellQuote(path.posix.join(root, "attachments"))}`);
+            if (!mk.ok || mk.exitCode !== 0)
+                return refused(`attachment materialization failed (createDir attachments/): ${mk.ok ? mk.stderr.trim() || `exit ${mk.exitCode}` : mk.error}`);
+            for (const p of placements) {
+                let bytes;
+                try {
+                    bytes = await attachmentBytesOf(seat.store, p.record);
+                }
+                catch (e) {
+                    return refused(errText(e));
+                }
+                const w = await channel.write(path.posix.join(root, p.relPath), bytes);
+                if (!w.ok)
+                    return refused(`attachment materialization failed (write ${p.relPath}): ${w.error}`);
+            }
+            seat.logger?.info("attachments_materialized", { sessionId: seat.sessionId, count: placements.length });
+            return FILLED;
+        },
+    };
+}
+async function seedInto(channel, root, seat) {
+    let seed;
+    try {
+        seed = await seedOfSession(seat.store, seat.sessionId);
+    }
+    catch (e) {
+        return refused(`workspace seeding failed (reading the session's project bundle from the attachment store): ${errText(e)}`);
+    }
+    if (seed === undefined)
+        return FILLED;
+    if ("broken" in seed)
+        return refused(`workspace seeding failed: ${seed.broken}`, true);
+    const id = seed.record.id;
+    const reading = await readProjectBundle(seed.bytes, { canonical: true });
+    if (!reading.ok)
+        return refused(`workspace seeding failed: the session's project bundle ${id} does not read as a project bundle (${reading.reason}${reading.path !== undefined ? ` at '${reading.path}'` : ""}: ${reading.detail})`, true);
+    const stem = `/tmp/sema-seed-${randomUUID()}`;
+    const archive = `${stem}.tgz`;
+    const names = `${stem}.names`;
+    const wn = await channel.write(names, new TextEncoder().encode(reading.topLevel.map((n) => `${n}\n`).join("")));
+    if (!wn.ok)
+        return refused(`workspace seeding failed (writing the bundle's top-level names to ${names}): ${wn.error}`);
+    const wa = await channel.write(archive, reading.canonical);
+    if (!wa.ok) {
+        await channel.run(`rm -f ${shellQuote(names)}`);
+        return refused(`workspace seeding failed (writing the bundle to ${archive}): ${wa.error}`);
+    }
+    const r = await channel.run(seedCommand(root, archive, names));
+    if (!r.ok)
+        return refused(`workspace seeding failed (unpacking the project bundle ${id}): ${r.error}`);
+    if (r.exitCode === SEED_NO_TAR_EXIT) {
+        return refused(`workspace seeding failed: this isolated lane's image has no \`tar\` — seeding a project bundle needs \`tar\` with gzip support in the sandbox image (the same tool the k8s workspace snapshots use)`, true);
+    }
+    if (r.exitCode === SEED_COLLISION_EXIT) {
+        const hit = r.stdout.split("\n").find((l) => l.startsWith(SEED_COLLISION_MARK))?.slice(SEED_COLLISION_MARK.length) ?? "?";
+        return refused(`workspace seeding failed: '${hit}' of the project bundle ${id} already exists in the freshly minted workspace ${root} (the sandbox image presets it) — the seed neither overwrites nor merges; rename it in the project, or remove it from the image's working directory`, true);
+    }
+    if (r.exitCode !== 0)
+        return refused(`workspace seeding failed (unpacking the project bundle ${id} exited ${r.exitCode}): ${r.stderr.trim().slice(0, 300)}`);
+    seat.logger?.info("workspace_seeded", { sessionId: seat.sessionId, bundleId: id, entries: reading.entries });
+    return FILLED;
+}
+export function seedCommand(root, archive, names) {
+    const R = shellQuote(root);
+    const A = shellQuote(archive);
+    const N = shellQuote(names);
+    return (`r=0; mkdir -p ${R} || r=$?; ` +
+        `if [ "$r" = 0 ] && ! command -v tar >/dev/null 2>&1; then r=${SEED_NO_TAR_EXIT}; fi; ` +
+        `if [ "$r" = 0 ]; then while IFS= read -r p; do if [ -e ${R}/"$p" ] || [ -L ${R}/"$p" ]; then printf '${SEED_COLLISION_MARK}%s\\n' "$p"; r=${SEED_COLLISION_EXIT}; break; fi; done < ${N}; fi; ` +
+        `if [ "$r" = 0 ]; then tar -x -z -o -f ${A} -C ${R} || r=$?; fi; ` +
+        `rm -f ${A} ${N}; exit "$r"`);
+}
+//# sourceMappingURL=workspace-fill.js.map