@sema-agent/server 1.288.0 → 1.289.0

package/dist/config.d.ts

@@ -179,6 +179,9 @@ export interface ServiceConfig {
     metricsToken?: string;
     traceToken?: string;
     corsOrigins: string[];
+    attachmentMaxBytes: number;
+    attachmentMimeAllowlist?: string[];
+    attachmentUnboundTtlMs: number;
     principalHeader: string;
     requirePrincipal: boolean;
     autonomy?: Autonomy;

package/dist/config.js

@@ -544,6 +544,11 @@ export function loadConfig() {
         metricsToken: process.env.METRICS_TOKEN || undefined,
         traceToken: process.env.TRACE_TOKEN || undefined,
         corsOrigins: (process.env.CORS_ORIGIN ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+        attachmentMaxBytes: Math.max(1024, numEnv("ATTACHMENT_MAX_BYTES", String(32 * 1024 * 1024))),
+        ...(process.env.ATTACHMENT_MIME_ALLOWLIST
+            ? { attachmentMimeAllowlist: process.env.ATTACHMENT_MIME_ALLOWLIST.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean) }
+            : {}),
+        attachmentUnboundTtlMs: Math.max(60_000, numEnv("ATTACHMENT_UNBOUND_TTL_MS", String(24 * 3600 * 1000))),
         principalHeader: headerNameEnv("PRINCIPAL_HEADER", "x-agent-principal"),
         requirePrincipal: process.env.REQUIRE_PRINCIPAL === "true",
         autonomy: parseAutonomy(process.env.AUTONOMY),

package/dist/http/server.d.ts

@@ -7,6 +7,7 @@ import { type OwnerAwareSessionStore } from "../security.js";
 import type { BakeState, BakeErrorCode } from "../plugins/tidb-image-bake.js";
 import type { RunStore, ApprovalStore, ImageIndex, ImageBake, CheckpointStoreFull, ResumeAnchorStore, ApprovalExemptionStore, ServiceSessionPolicyStore, ServiceFileSnapshotStore, StoreBackend } from "../plugins/store-backend.js";
 import { type MemorySyncRequest, type MemorySyncResponse } from "../memory-sync.js";
+import type { TaskAttachmentStore } from "../plugins/task-attachment-store.js";
 import type { LeaderEndpoint } from "../leader/endpoint.js";
 import { type WorkflowAgentRegistry } from "../orchestration/workflow-agent-steer.js";
 import type { SubagentSteerRegistry } from "../orchestration/subagent-steer.js";
@@ -70,6 +71,7 @@ export interface ServiceDeps {
     parkedReviveTool?: import("@sema-agent/core").ToolSpec;
     parkedKnownAgentTypes?: ReadonlySet<string>;
     parkedReviveInheritedGate?: (row: import("@sema-agent/core").BackgroundAgentRecord) => unknown;
+    taskAttachmentStore?: TaskAttachmentStore;
     imageIndex?: ImageIndex;
     imageBakes?: ImageBake;
     leaderEndpoint?: LeaderEndpoint;
@@ -165,6 +167,7 @@ export interface TaskRequestBody {
     } | {
         url: string;
     }>;
+    attachmentIds?: string[];
     clientContext?: {
         timeZone?: string;
         userEmail?: string;

package/dist/http/server.js

@@ -1,7 +1,7 @@
 import http from "node:http";
 import { once } from "node:events";
 import { timingSafeEqual, createHash, randomBytes } from "node:crypto";
-import { sessionLogDigest, sessionLogDigestsComparable, uuidv7, callKeyOrdinal, isThinkingLevel, DEFAULT_EFFORT_LEVELS, expandTiers, materializeMcpTools, runWithVerification, resumeWithVerification, runCascade, CheckpointError, mintCheckpointToken, SessionPolicyError, SessionError, HAND_TOOL_EFFECTS, canonicalToolName, formatUserScope, defaultTaskRegistry, validatePendingSteer, StreamingImportValidator, getWorkflowRun, subscribeWorkflow, deriveAgentDisplayStatus } from "@sema-agent/core";
+import { sessionLogDigest, sessionLogDigestsComparable, uuidv7, sanitizePathComponent, callKeyOrdinal, isThinkingLevel, DEFAULT_EFFORT_LEVELS, expandTiers, materializeMcpTools, runWithVerification, resumeWithVerification, runCascade, CheckpointError, mintCheckpointToken, SessionPolicyError, SessionError, HAND_TOOL_EFFECTS, canonicalToolName, formatUserScope, defaultTaskRegistry, validatePendingSteer, StreamingImportValidator, getWorkflowRun, subscribeWorkflow, deriveAgentDisplayStatus } from "@sema-agent/core";
 import { decideParkedAgent, findParkedAgentForCheckpoint } from "../parked-decide.js";
 import { matchCatalogModel } from "../model-select.js";
 import { mcpForScenario } from "../sema-registry.js";
@@ -4347,6 +4347,96 @@ export function createHttpServer(deps) {
                 return;
             }
         }
+        {
+            const am = /^\/v1\/attachments(?:\/([^/?]+))?$/.exec(url);
+            if (am) {
+                if (rateLimited(req, res) || quotaExceeded(req, res))
+                    return;
+                const store = deps.taskAttachmentStore;
+                if (!store) {
+                    sendJson(res, 501, { error: "attachment store not configured" });
+                    return;
+                }
+                const principal = gatedPrincipal(req, deps.config);
+                if (deps.config.requirePrincipal && principal === undefined) {
+                    sendJson(res, 401, { error: `missing principal header '${deps.config.principalHeader}'` });
+                    return;
+                }
+                const owner = principal ?? "default";
+                const attId = am[1] !== undefined ? safeDecode(am[1]) : undefined;
+                if (attId === undefined && req.method === "POST") {
+                    const q = new URL(req.url ?? "", "http://x").searchParams;
+                    const rawName = q.get("name");
+                    const base = ((rawName ?? "").split(/[/\\]/).filter(Boolean).pop() ?? "").slice(0, 128);
+                    if (!rawName || base === "" || base === "." || base === ".." || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(base)) {
+                        sendJson(res, 400, { error: "query param `name` is required and must reduce to a safe basename ([A-Za-z0-9._-], not starting with a dot)" });
+                        return;
+                    }
+                    const name = sanitizePathComponent(base);
+                    const mime = String(req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+                    if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mime) || mime.length > 128) {
+                        sendJson(res, 400, { error: "content-type must be a well-formed mime type (type/subtype)" });
+                        return;
+                    }
+                    const allow = deps.config.attachmentMimeAllowlist;
+                    if (allow && !allow.some((a) => a === mime || (a.endsWith("/*") && mime.startsWith(a.slice(0, -1))))) {
+                        sendJson(res, 415, { code: "attachment.mime_not_allowed", error: `mime '${mime}' is not in this deployment's allowlist`, allowed: allow });
+                        return;
+                    }
+                    const max = deps.config.attachmentMaxBytes ?? 32 * 1024 * 1024;
+                    let body;
+                    try {
+                        body = await readRawBody(req, max);
+                    }
+                    catch (err) {
+                        if (err instanceof HttpError && err.status === 413) {
+                            sendJson(res, 413, { code: "attachment.too_large", error: `attachment exceeds the per-file limit (${max} bytes)`, maxBytes: max });
+                            return;
+                        }
+                        throw err;
+                    }
+                    const rec = {
+                        id: uuidv7(),
+                        owner,
+                        name,
+                        mime,
+                        sha256: createHash("sha256").update(body).digest("hex"),
+                        sizeBytes: body.length,
+                        createdAtMs: Date.now(),
+                    };
+                    await store.put({ ...rec, content: new Uint8Array(body) });
+                    deps.metrics?.inc("attachment_uploads_total");
+                    sendJson(res, 201, { id: rec.id, name: rec.name, mime: rec.mime, sha256: rec.sha256, sizeBytes: rec.sizeBytes });
+                    return;
+                }
+                if (attId !== undefined && attId !== null && req.method === "GET") {
+                    const meta = await store.get(owner, attId);
+                    const bytes = meta ? await store.getContent(owner, attId) : null;
+                    if (!meta || !bytes) {
+                        sendJson(res, 404, { error: "not found" });
+                        return;
+                    }
+                    res.writeHead(200, {
+                        "content-type": meta.mime,
+                        "content-length": String(bytes.byteLength),
+                        "content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(meta.name)}`,
+                    });
+                    res.end(Buffer.from(bytes));
+                    return;
+                }
+                if (attId !== undefined && attId !== null && req.method === "DELETE") {
+                    const ok = await store.delete(owner, attId);
+                    if (!ok) {
+                        sendJson(res, 404, { error: "not found" });
+                        return;
+                    }
+                    res.writeHead(204).end();
+                    return;
+                }
+                sendJson(res, 404, { error: "not found" });
+                return;
+            }
+        }
         if (req.method === "POST" && /^\/v1\/sessions\/[^/]+\/notify$/.test(url)) {
             if (rateLimited(req, res) || quotaExceeded(req, res))
                 return;

package/dist/main.js

@@ -78,6 +78,9 @@ import { createConfigProvider, raceBootFetch, BOOT_FETCH_DEFERRED } from "./conf
 import { validatePromptsDomain, centerPromptProvider, centerIdentityAssembled, applyCatalogToSource, CORE_ENGINE_VERSION, withPromptArtifactBackfill } from "./capabilities/center-prompts.js";
 import { defaultLkgPath, defaultSkillCacheDir, saveLkg, loadLkg } from "./config-lkg.js";
 import { TiDBRosterStore, PgRosterStore, ensureTiDBRosterSchema, ensurePgRosterSchema } from "./plugins/roster-store-sql.js";
+import { TiDBTaskAttachmentStore, PgTaskAttachmentStore, ensureTiDBTaskAttachmentSchema, ensurePgTaskAttachmentSchema, bindAttachmentsForTask, materializeAttachmentsInto } from "./plugins/task-attachment-store.js";
+import { LocalTaskAttachmentStore } from "./plugins/local-task-attachment-store.js";
+import { MinioBlobBackend } from "./plugins/blob-backend.js";
 import { TiDBBackgroundAgentStore, PgBackgroundAgentStore, ensureTiDBBackgroundAgentSchema, ensurePgBackgroundAgentSchema } from "./plugins/background-agent-store-sql.js";
 import { TiDBMailboxStore, PgMailboxStore, ensureTiDBMailboxSchema, ensurePgMailboxSchema } from "./plugins/mailbox-store-sql.js";
 import { createPrincipalCapsClient, gateExecutionLane, scopedTokenNeedsWorker, applyObserverEnvOptIn } from "./runtime-caps-resolver.js";
@@ -535,6 +538,36 @@ async function main() {
         if (backgroundAgentStore)
             logger.info("background_agent_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : "file" });
     }
+    let taskAttachmentStore;
+    {
+        const mysqlPool = backend?.mysqlPool?.();
+        const pgPool = backend?.pgPool?.();
+        if (pgPool || mysqlPool) {
+            const minio = config.snapshotBlobStore;
+            if (!minio) {
+                logger.error("attachments_disabled_object_store_required", {
+                    hint: "cloud deployments must configure object storage (MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY) — attachment routes will 501 until it is set",
+                });
+            }
+            else {
+                const bytes = new MinioBlobBackend({ ...minio, keyPrefix: `${minio.keyPrefix ?? ""}attachments/` });
+                if (pgPool) {
+                    const q = async (text, params) => { const r = await pgPool.query(text, params); return { rows: r.rows }; };
+                    await ensurePgTaskAttachmentSchema(q);
+                    taskAttachmentStore = new PgTaskAttachmentStore(q, bytes);
+                }
+                else {
+                    await ensureTiDBTaskAttachmentSchema(mysqlPool);
+                    taskAttachmentStore = new TiDBTaskAttachmentStore(mysqlPool, bytes);
+                }
+            }
+        }
+        else if (backend?.kind === "local") {
+            taskAttachmentStore = new LocalTaskAttachmentStore(config.localDataRoot ?? localRoot);
+        }
+        if (taskAttachmentStore)
+            logger.info("task_attachment_store_enabled", { backend: pgPool ? "pg+minio" : mysqlPool ? "tidb+minio" : "file", maxBytes: config.attachmentMaxBytes });
+    }
     let mailboxStore;
     {
         const mysqlPool = backend?.mysqlPool?.();
@@ -804,6 +837,17 @@ async function main() {
         executionEnvFactory = registry.wrapFactory(executionEnvFactory);
         return registry;
     })();
+    if (taskAttachmentStore && executionEnvFactory) {
+        const inner = executionEnvFactory;
+        const attStore = taskAttachmentStore;
+        executionEnvFactory = async (ctx) => {
+            const env = await inner(ctx);
+            const n = await materializeAttachmentsInto(env, attStore, ctx.sessionId);
+            if (n > 0)
+                logger.info("attachments_materialized", { sessionId: ctx.sessionId, count: n });
+            return env;
+        };
+    }
     if (executionEnvFactory) {
         const isolated = config.remoteExec.provider === "e2b" ||
             config.remoteExec.provider === "k8s" ||
@@ -1381,6 +1425,7 @@ async function main() {
             costQuota.reap();
         void toolResultStore?.reapOlderThan?.(Date.now() - config.toolResultTtlSec * 1000)?.catch(() => undefined);
         void fileSnapshotStore?.sweepOrphanBlobs?.().catch(() => undefined);
+        void taskAttachmentStore?.reapUnbound(Date.now() - config.attachmentUnboundTtlMs).then(reapCount("attachments_reaped_total", {})).catch(() => undefined);
         void backend?.session()?.sweepStagingSessions?.().catch(() => undefined);
         void imageBakes?.reapStaleBakes(config.imageBakes.staleMs).then(reapCount("bakes_reaped_total", {})).catch(() => undefined);
         void worktreeReap?.();
@@ -1671,6 +1716,8 @@ async function main() {
                 await approvalExemptionStore.deleteBySession(sessionId);
             if (sessionPolicyStore?.deleteBySession)
                 await sessionPolicyStore.deleteBySession(sessionId);
+            if (taskAttachmentStore)
+                await taskAttachmentStore.deleteBySession(sessionId);
             if (fileSnapshotStore?.deleteBySession)
                 await fileSnapshotStore.deleteBySession(sessionId);
             if (workflowCompletionInbox)
@@ -1757,6 +1804,7 @@ async function main() {
         config,
         authorize,
         sessionStoreLabel: config.sessionBackend === "tidb" && backend ? `durable(${backend.kind})` : config.sessionBackend,
+        ...(taskAttachmentStore ? { taskAttachmentStore } : {}),
         modelReady: () => modelReadyState.ready,
         scenarioDetails,
         ...(registryJwtVerifier ? { registryJwtVerifier } : {}),
@@ -1850,6 +1898,38 @@ async function main() {
             if (parsedSettings.deferred.length > 0) {
                 logger.warn("task_settings_deferred", { fields: parsedSettings.deferred, sessionId: auth?.sessionId ?? null });
             }
+            let attachmentNotice;
+            {
+                const reqAtt = body.attachmentIds;
+                if (reqAtt !== undefined) {
+                    if (!Array.isArray(reqAtt) || !reqAtt.every((x) => typeof x === "string" && x.length > 0 && x.length <= 64)) {
+                        throw new HttpError(400, "`attachmentIds` must be an array of attachment ids (strings)");
+                    }
+                    if (reqAtt.length > 16)
+                        throw new HttpError(400, "`attachmentIds` exceeds the per-task limit (16)");
+                    if (reqAtt.length > 0) {
+                        if (!taskAttachmentStore)
+                            throw new HttpError(501, "attachmentIds require a store backend (DB_BACKEND=tidb|pg|local)");
+                        if (!auth?.sessionId)
+                            throw new HttpError(400, "`attachmentIds` requires a session-resolving deployment (no authorizer session)");
+                        const sid = auth.sessionId;
+                        const r = await bindAttachmentsForTask({
+                            store: taskAttachmentStore,
+                            owner: auth?.principal ?? "default",
+                            ids: reqAtt,
+                            sessionId: sid,
+                            leg: opts?.leg === "fresh" ? "fresh" : "resume",
+                            nowMs: Date.now(),
+                            onMissing: (id) => {
+                                if (opts?.leg === "fresh")
+                                    throw new HttpError(400, `attachment not found: ${id}`);
+                                logger.warn("attachment_missing_on_resume", { sessionId: sid, id });
+                            },
+                        });
+                        attachmentNotice = r.notice;
+                    }
+                }
+            }
             const execLane = config.remoteExec?.provider ?? "in-process";
             if (typeof body.cwd === "string" && body.cwd.length > 0 && auth?.sessionId) {
                 if (cwdHonored(config) && isValidCwd(body.cwd))
@@ -1943,7 +2023,7 @@ async function main() {
             const s4ProjectId = auth?.resolvedProjectId ?? (typeof body.projectId === "string" && body.projectId ? body.projectId : undefined);
             const s4DefaultScopes = s4ProjectId ? config.projects[s4ProjectId]?.defaultScopes : undefined;
             const spec = {
-                objective: picked.cleanedObjective,
+                objective: attachmentNotice ? `${picked.cleanedObjective}\n\n${attachmentNotice}` : picked.cleanedObjective,
                 systemPrompt: typeof body.systemPrompt === "string" ? body.systemPrompt : undefined,
                 appendSystemPrompt: acceptedAppend,
                 sessionId: auth?.sessionId,

package/dist/plugins/local-task-attachment-store.d.ts

@@ -0,0 +1,20 @@
+import type { TaskAttachmentStore, TaskAttachmentRecord } from "./task-attachment-store.js";
+export declare class LocalTaskAttachmentStore implements TaskAttachmentStore {
+    private readonly dir;
+    private metas;
+    constructor(rootDir: string);
+    private hydrate;
+    put(rec: TaskAttachmentRecord & {
+        content: Uint8Array;
+    }): Promise<void>;
+    get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
+    getContent(owner: string, id: string): Promise<Uint8Array | null>;
+    private persistMeta;
+    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
+    private removeRow;
+    delete(owner: string, id: string): Promise<boolean>;
+    deleteBySession(sessionId: string): Promise<number>;
+    reapUnbound(olderThanMs: number): Promise<number>;
+}
+//# sourceMappingURL=local-task-attachment-store.d.ts.map

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

@@ -0,0 +1,115 @@
+import { promises as fsp } from "node:fs";
+import { join } from "node:path";
+const ID_RE = /^[0-9a-f-]{16,64}$/i;
+export class LocalTaskAttachmentStore {
+    dir;
+    metas;
+    constructor(rootDir) {
+        this.dir = join(rootDir, "attachments");
+    }
+    async hydrate() {
+        if (this.metas)
+            return this.metas;
+        const m = new Map();
+        try {
+            for (const f of await fsp.readdir(this.dir)) {
+                if (!f.endsWith(".json"))
+                    continue;
+                const id = f.slice(0, -5);
+                if (!ID_RE.test(id))
+                    continue;
+                try {
+                    const meta = JSON.parse(await fsp.readFile(join(this.dir, f), "utf8"));
+                    if (meta && meta.id === id)
+                        m.set(id, meta);
+                }
+                catch {
+                }
+            }
+        }
+        catch {
+        }
+        this.metas = m;
+        return m;
+    }
+    async put(rec) {
+        const metas = await this.hydrate();
+        await fsp.mkdir(this.dir, { recursive: true });
+        const { content, ...meta } = rec;
+        const binTmp = join(this.dir, `${rec.id}.bin.tmp`);
+        const metaTmp = join(this.dir, `${rec.id}.json.tmp`);
+        await fsp.writeFile(binTmp, Buffer.from(content));
+        await fsp.rename(binTmp, join(this.dir, `${rec.id}.bin`));
+        await fsp.writeFile(metaTmp, JSON.stringify(meta));
+        await fsp.rename(metaTmp, join(this.dir, `${rec.id}.json`));
+        metas.set(rec.id, { ...meta });
+    }
+    async get(owner, id) {
+        const m = (await this.hydrate()).get(id);
+        return m && m.owner === owner ? { ...m } : null;
+    }
+    async getContent(owner, id) {
+        const m = (await this.hydrate()).get(id);
+        if (!m || m.owner !== owner)
+            return null;
+        try {
+            return new Uint8Array(await fsp.readFile(join(this.dir, `${id}.bin`)));
+        }
+        catch {
+            return null;
+        }
+    }
+    async persistMeta(m) {
+        const tmp = join(this.dir, `${m.id}.json.tmp`);
+        await fsp.writeFile(tmp, JSON.stringify(m));
+        await fsp.rename(tmp, join(this.dir, `${m.id}.json`));
+    }
+    async bind(owner, ids, sessionId, boundAtMs) {
+        const metas = await this.hydrate();
+        let bound = 0;
+        for (const id of ids) {
+            const m = metas.get(id);
+            if (!m || m.owner !== owner)
+                continue;
+            m.sessionId = sessionId;
+            m.boundAtMs = boundAtMs;
+            await this.persistMeta(m);
+            bound++;
+        }
+        return bound;
+    }
+    async listBySession(sessionId) {
+        const metas = await this.hydrate();
+        return [...metas.values()]
+            .filter((m) => m.sessionId === sessionId)
+            .sort((a, b) => a.createdAtMs - b.createdAtMs || (a.id < b.id ? -1 : 1))
+            .map((m) => ({ ...m }));
+    }
+    async removeRow(id) {
+        await fsp.rm(join(this.dir, `${id}.json`), { force: true });
+        await fsp.rm(join(this.dir, `${id}.bin`), { force: true });
+        this.metas?.delete(id);
+    }
+    async delete(owner, id) {
+        const m = (await this.hydrate()).get(id);
+        if (!m || m.owner !== owner)
+            return false;
+        await this.removeRow(id);
+        return true;
+    }
+    async deleteBySession(sessionId) {
+        const metas = await this.hydrate();
+        const hit = [...metas.values()].filter((m) => m.sessionId === sessionId);
+        for (const m of hit)
+            await this.removeRow(m.id);
+        return hit.length;
+    }
+    async reapUnbound(olderThanMs) {
+        const metas = await this.hydrate();
+        const hit = [...metas.values()].filter((m) => m.sessionId === undefined && m.createdAtMs < olderThanMs);
+        for (const m of hit)
+            await this.removeRow(m.id);
+        return hit.length;
+    }
+}
+//# sourceMappingURL=local-task-attachment-store.js.map

package/dist/plugins/task-attachment-store.d.ts

@@ -0,0 +1,98 @@
+import type { Pool } from "mysql2/promise";
+import type { PgQueryFn } from "./pg-query.js";
+export interface TaskAttachmentRecord {
+    id: string;
+    owner: string;
+    name: string;
+    mime: string;
+    sha256: string;
+    sizeBytes: number;
+    createdAtMs: number;
+    sessionId?: string;
+    boundAtMs?: number;
+}
+export interface TaskAttachmentStore {
+    put(rec: TaskAttachmentRecord & {
+        content: Uint8Array;
+    }): Promise<void>;
+    get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
+    getContent(owner: string, id: string): Promise<Uint8Array | null>;
+    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
+    delete(owner: string, id: string): Promise<boolean>;
+    deleteBySession(sessionId: string): Promise<number>;
+    reapUnbound(olderThanMs: number): Promise<number>;
+}
+export declare const TASK_ATTACHMENT_TABLE = "task_attachment";
+export interface AttachmentBytesStore {
+    putBlob(hash: string, bytes: Uint8Array): Promise<void>;
+    getBlob(hash: string): Promise<Uint8Array | undefined>;
+    deleteBlobs(hashes: string[]): Promise<number>;
+}
+export declare function materializedRelPaths(atts: TaskAttachmentRecord[]): Map<string, string>;
+export declare function bindAttachmentsForTask(opts: {
+    store: TaskAttachmentStore;
+    owner: string;
+    ids: string[];
+    sessionId: string;
+    leg: "fresh" | "resume";
+    nowMs: number;
+    onMissing: (id: string) => void | never;
+}): Promise<{
+    notice: string | undefined;
+}>;
+export declare function materializeAttachmentsInto(env: {
+    createDir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<{
+        ok: boolean;
+        error?: {
+            message?: string;
+        };
+    } | {
+        ok: true;
+    }>;
+    writeFile(path: string, content: string | Uint8Array): Promise<{
+        ok: boolean;
+        error?: {
+            message?: string;
+        };
+    } | {
+        ok: true;
+    }>;
+}, store: TaskAttachmentStore, sessionId: string): Promise<number>;
+export declare function ensureTiDBTaskAttachmentSchema(pool: Pool): Promise<void>;
+export declare function ensurePgTaskAttachmentSchema(q: PgQueryFn): Promise<void>;
+export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
+    private readonly pool;
+    private readonly bytes;
+    constructor(pool: Pool, bytes: AttachmentBytesStore);
+    put(rec: TaskAttachmentRecord & {
+        content: Uint8Array;
+    }): Promise<void>;
+    get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
+    getContent(owner: string, id: string): Promise<Uint8Array | null>;
+    private deleteBytesIfUnreferenced;
+    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
+    delete(owner: string, id: string): Promise<boolean>;
+    deleteBySession(sessionId: string): Promise<number>;
+    reapUnbound(olderThanMs: number): Promise<number>;
+}
+export declare class PgTaskAttachmentStore implements TaskAttachmentStore {
+    private readonly q;
+    private readonly bytes;
+    constructor(q: PgQueryFn, bytes: AttachmentBytesStore);
+    put(rec: TaskAttachmentRecord & {
+        content: Uint8Array;
+    }): Promise<void>;
+    get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
+    getContent(owner: string, id: string): Promise<Uint8Array | null>;
+    private deleteBytesIfUnreferenced;
+    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
+    delete(owner: string, id: string): Promise<boolean>;
+    deleteBySession(sessionId: string): Promise<number>;
+    reapUnbound(olderThanMs: number): Promise<number>;
+}
+//# sourceMappingURL=task-attachment-store.d.ts.map

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

@@ -0,0 +1,224 @@
+export const TASK_ATTACHMENT_TABLE = "task_attachment";
+export function materializedRelPaths(atts) {
+    const used = new Set();
+    const out = new Map();
+    for (const a of atts) {
+        const n = used.has(a.name) ? `${a.id.slice(0, 8)}-${a.name}` : a.name;
+        used.add(n);
+        out.set(a.id, `attachments/${n}`);
+    }
+    return out;
+}
+const COLS = "id, owner, name, mime, sha256, size_bytes, session_id, created_at_ms, bound_at_ms";
+function rowToRecord(r) {
+    return {
+        id: String(r.id),
+        owner: String(r.owner),
+        name: String(r.name),
+        mime: String(r.mime),
+        sha256: String(r.sha256),
+        sizeBytes: Number(r.size_bytes),
+        createdAtMs: Number(r.created_at_ms),
+        ...(r.session_id !== null && r.session_id !== undefined ? { sessionId: String(r.session_id) } : {}),
+        ...(r.bound_at_ms !== null && r.bound_at_ms !== undefined ? { boundAtMs: Number(r.bound_at_ms) } : {}),
+    };
+}
+export async function bindAttachmentsForTask(opts) {
+    const found = [];
+    for (const id of opts.ids) {
+        const rec = await opts.store.get(opts.owner, id);
+        if (!rec) {
+            opts.onMissing(id);
+            continue;
+        }
+        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")}` };
+}
+export async function materializeAttachmentsInto(env, store, sessionId) {
+    const atts = await store.listBySession(sessionId);
+    if (atts.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);
+        if (!w.ok)
+            throw new Error(`attachment materialization failed (write ${paths.get(a.id)}): ${String(w.error?.message ?? "unknown")}`);
+    }
+    return atts.length;
+}
+export async function ensureTiDBTaskAttachmentSchema(pool) {
+    await pool.query(`CREATE TABLE IF NOT EXISTS ${TASK_ATTACHMENT_TABLE} (
+    id VARCHAR(64) NOT NULL,
+    -- owner = auth principal ?? "default"(单库 tenant 轴;server 端从凭据推导,非用户输入)
+    owner VARCHAR(190) NOT NULL,
+    name VARCHAR(255) NOT NULL,
+    mime VARCHAR(128) NOT NULL,
+    sha256 CHAR(64) NOT NULL,
+    size_bytes INT NOT NULL,
+    -- 绑定轴:提交 task 时钉上;NULL = 上传后未被引用(TTL 收割对象)
+    session_id VARCHAR(190) NULL,
+    created_at_ms BIGINT NOT NULL,
+    bound_at_ms BIGINT NULL,
+    PRIMARY KEY (id),
+    KEY idx_att_session (session_id),
+    KEY idx_att_unbound (created_at_ms)
+  ) COLLATE utf8mb4_bin`);
+}
+export async function ensurePgTaskAttachmentSchema(q) {
+    await q(`CREATE TABLE IF NOT EXISTS ${TASK_ATTACHMENT_TABLE} (
+    id VARCHAR(64) NOT NULL,
+    -- owner:隔离键,'=' 必须字节等价(bga F2 同姿)
+    owner VARCHAR(190) COLLATE "C" NOT NULL,
+    name VARCHAR(255) NOT NULL,
+    mime VARCHAR(128) NOT NULL,
+    sha256 CHAR(64) NOT NULL,
+    size_bytes INT NOT NULL,
+    session_id VARCHAR(190),
+    created_at_ms BIGINT NOT NULL,
+    bound_at_ms BIGINT,
+    PRIMARY KEY (id)
+  )`);
+    await q(`CREATE INDEX IF NOT EXISTS idx_att_session ON ${TASK_ATTACHMENT_TABLE} (session_id)`);
+    await q(`CREATE INDEX IF NOT EXISTS idx_att_unbound ON ${TASK_ATTACHMENT_TABLE} (created_at_ms)`);
+}
+export class TiDBTaskAttachmentStore {
+    pool;
+    bytes;
+    constructor(pool, bytes) {
+        this.pool = pool;
+        this.bytes = bytes;
+    }
+    async put(rec) {
+        await this.bytes.putBlob(rec.sha256, rec.content);
+        await this.pool.execute(`INSERT INTO ${TASK_ATTACHMENT_TABLE} (${COLS}) VALUES (?,?,?,?,?,?,?,?,?)`, [rec.id, rec.owner, rec.name, rec.mime, rec.sha256, rec.sizeBytes, rec.sessionId ?? null, rec.createdAtMs, rec.boundAtMs ?? null]);
+    }
+    async get(owner, id) {
+        const [rows] = await this.pool.query(`SELECT ${COLS} FROM ${TASK_ATTACHMENT_TABLE} WHERE id = ? AND owner = ?`, [id, owner]);
+        return rows.length ? rowToRecord(rows[0]) : null;
+    }
+    async getContent(owner, id) {
+        const meta = await this.get(owner, id);
+        if (!meta)
+            return null;
+        const b = await this.bytes.getBlob(meta.sha256);
+        return b && b.byteLength === meta.sizeBytes ? b : null;
+    }
+    async deleteBytesIfUnreferenced(shas) {
+        for (const sha of new Set(shas)) {
+            try {
+                const [cnt] = await this.pool.query(`SELECT COUNT(*) AS n FROM ${TASK_ATTACHMENT_TABLE} WHERE sha256 = ?`, [sha]);
+                if (Number(cnt[0].n) === 0)
+                    await this.bytes.deleteBlobs([sha]);
+            }
+            catch {
+            }
+        }
+    }
+    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;
+    }
+    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]);
+        return rows.map((r) => rowToRecord(r));
+    }
+    async delete(owner, id) {
+        const meta = await this.get(owner, id);
+        if (!meta)
+            return false;
+        const [res] = await this.pool.query(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE id = ? AND owner = ?`, [id, owner]);
+        if ((res.affectedRows ?? 0) === 0)
+            return false;
+        await this.deleteBytesIfUnreferenced([meta.sha256]);
+        return true;
+    }
+    async deleteBySession(sessionId) {
+        const [rows] = await this.pool.query(`SELECT sha256 FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id = ?`, [sessionId]);
+        const [res] = await this.pool.query(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id = ?`, [sessionId]);
+        await this.deleteBytesIfUnreferenced(rows.map((r) => r.sha256));
+        return res.affectedRows ?? 0;
+    }
+    async reapUnbound(olderThanMs) {
+        const [rows] = await this.pool.query(`SELECT sha256 FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id IS NULL AND created_at_ms < ?`, [olderThanMs]);
+        const [res] = await this.pool.query(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id IS NULL AND created_at_ms < ?`, [olderThanMs]);
+        await this.deleteBytesIfUnreferenced(rows.map((r) => r.sha256));
+        return res.affectedRows ?? 0;
+    }
+}
+export class PgTaskAttachmentStore {
+    q;
+    bytes;
+    constructor(q, bytes) {
+        this.q = q;
+        this.bytes = bytes;
+    }
+    async put(rec) {
+        await this.bytes.putBlob(rec.sha256, rec.content);
+        await this.q(`INSERT INTO ${TASK_ATTACHMENT_TABLE} (${COLS}) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)`, [rec.id, rec.owner, rec.name, rec.mime, rec.sha256, rec.sizeBytes, rec.sessionId ?? null, rec.createdAtMs, rec.boundAtMs ?? null]);
+    }
+    async get(owner, id) {
+        const res = await this.q(`SELECT ${COLS} FROM ${TASK_ATTACHMENT_TABLE} WHERE id = $1 AND owner = $2`, [id, owner]);
+        return res.rows.length ? rowToRecord(res.rows[0]) : null;
+    }
+    async getContent(owner, id) {
+        const meta = await this.get(owner, id);
+        if (!meta)
+            return null;
+        const b = await this.bytes.getBlob(meta.sha256);
+        return b && b.byteLength === meta.sizeBytes ? b : null;
+    }
+    async deleteBytesIfUnreferenced(shas) {
+        for (const sha of new Set(shas)) {
+            try {
+                const res = await this.q(`SELECT COUNT(*) AS n FROM ${TASK_ATTACHMENT_TABLE} WHERE sha256 = $1`, [sha]);
+                if (Number(res.rows[0].n) === 0)
+                    await this.bytes.deleteBlobs([sha]);
+            }
+            catch {
+            }
+        }
+    }
+    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;
+    }
+    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]);
+        return res.rows.map((r) => rowToRecord(r));
+    }
+    async delete(owner, id) {
+        const res = await this.q(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE id = $1 AND owner = $2 RETURNING sha256`, [id, owner]);
+        if (res.rows.length === 0)
+            return false;
+        await this.deleteBytesIfUnreferenced([res.rows[0].sha256]);
+        return true;
+    }
+    async deleteBySession(sessionId) {
+        const res = await this.q(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id = $1 RETURNING sha256`, [sessionId]);
+        await this.deleteBytesIfUnreferenced(res.rows.map((r) => r.sha256));
+        return res.rows.length;
+    }
+    async reapUnbound(olderThanMs) {
+        const res = await this.q(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id IS NULL AND created_at_ms < $1 RETURNING sha256`, [olderThanMs]);
+        await this.deleteBytesIfUnreferenced(res.rows.map((r) => r.sha256));
+        return res.rows.length;
+    }
+}
+//# sourceMappingURL=task-attachment-store.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "1.288.0",
+  "version": "1.289.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",