@sema-agent/server 1.290.0 → 1.291.0

package/dist/env-facts.d.ts

@@ -25,6 +25,11 @@ export declare function resumeFactsForLane(provider: "e2b" | "k8s" | "ssh" | "ad
 export declare function scratchpadSessionSegment(sessionId: string): string;
 export declare function scratchpadDirFor(localDataRoot: string, sessionId: string): string;
 export declare function ensureScratchpadDir(localDataRoot: string, sessionId: string): Promise<string | undefined>;
+export declare function acceptShellScratchpadDir(raw: unknown, opts: {
+    requirePrincipal: boolean;
+    hostSemanticsLane: boolean;
+    warn: (msg: string, meta?: object) => void;
+}): Promise<string | undefined>;
 export declare function purgeScratchpadDir(localDataRoot: string, sessionId: string): Promise<void>;
 export declare function sweepStaleScratchpads(localDataRoot: string, opts: {
     olderThanMs: number;

package/dist/env-facts.js

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { isAbsolute, join, resolve, sep } from "node:path";
 import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 const MAX_STR = 64;
@@ -59,6 +59,40 @@ export async function ensureScratchpadDir(localDataRoot, sessionId) {
         return undefined;
     }
 }
+export async function acceptShellScratchpadDir(raw, opts) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return undefined;
+    if (opts.requirePrincipal) {
+        opts.warn("shell_scratchpad_ignored", { reason: "multi_tenant", note: "tenant-supplied exempt dir on a shared worker disk — server-computed scratchpad used instead" });
+        return undefined;
+    }
+    if (!opts.hostSemanticsLane) {
+        opts.warn("shell_scratchpad_ignored", { reason: "remote_lane", note: "worker-local path is not real to remote-sandbox hands — in-sandbox scratchpad used instead" });
+        return undefined;
+    }
+    if (!isAbsolute(raw)) {
+        opts.warn("shell_scratchpad_ignored", { reason: "not_absolute" });
+        return undefined;
+    }
+    if (raw.length > MAX_PATH) {
+        opts.warn("shell_scratchpad_ignored", { reason: "too_long", length: raw.length, max: MAX_PATH });
+        return undefined;
+    }
+    const canonical = resolve(raw);
+    const depth = canonical.split(sep).filter((s) => s.length > 0).length;
+    if (depth < 3) {
+        opts.warn("shell_scratchpad_ignored", { reason: "too_shallow", canonical });
+        return undefined;
+    }
+    try {
+        await mkdir(canonical, { recursive: true });
+        return canonical;
+    }
+    catch (err) {
+        opts.warn("shell_scratchpad_ignored", { reason: "mkdir_failed", error: err instanceof Error ? err.message : String(err) });
+        return undefined;
+    }
+}
 export async function purgeScratchpadDir(localDataRoot, sessionId) {
     const dir = scratchpadDirFor(localDataRoot, sessionId);
     try {

package/dist/fleet/fleet-bus.d.ts

@@ -23,6 +23,20 @@ export interface FleetTaskRow {
     };
     toolUses?: number;
     transcriptId?: string;
+    stoppedBy?: string;
+    usage?: {
+        totalTokens?: number;
+        toolUses?: number;
+        durationMs?: number;
+        tokens?: number;
+        turns?: number;
+        costMicroUsd?: number;
+    };
+    resumable?: boolean;
+    editedFiles?: Array<{
+        path: string;
+        edits: number;
+    }>;
 }
 export interface FleetWorkflowRow {
     id: string;
@@ -161,9 +175,27 @@ export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
         status?: string;
     }) => void;
     onChildTerminal: (taskId: string, status: string, altId?: string, toolUseId?: string) => boolean;
-    onTerminal: (status: string) => void;
+    onTerminal: (status: string, residuals?: {
+        usage?: FleetTaskRow["usage"];
+        stoppedBy?: string;
+        transcriptId?: string;
+    }) => void;
 };
 export type FleetRunPublisher = ReturnType<typeof fleetRunPublisher>;
+export declare function fleetRunResiduals(result: {
+    sessionId?: string;
+    errorCode?: string;
+    stats?: {
+        turns?: number;
+        tokens?: number;
+        toolCalls?: number;
+        costMicroUsd?: number;
+    };
+} | null | undefined): {
+    usage?: FleetTaskRow["usage"];
+    stoppedBy?: string;
+    transcriptId?: string;
+};
 export declare function fleetBackgroundChildPublisher(bus?: FleetEventBus, log?: (msg: string, fields: Record<string, unknown>) => void): (e: import("@sema-agent/core").BackgroundChildEvent) => void;
 export declare function fleetRunLabels(objective: string | undefined): {
     name: string;

package/dist/fleet/fleet-bus.js

@@ -136,21 +136,47 @@ export function fleetRunPublisher(bus, run) {
             }
             return hadRow;
         },
-        onTerminal(status) {
+        onTerminal(status, residuals) {
             settledLeg = true;
             const fleetStatus = runStatusToFleet(status);
-            bus.publishTask({ id: run.runId, status: fleetStatus, tokens, elapsedMs: Date.now() - startedAt });
+            const terminal = fleetStatus === "completed" || fleetStatus === "failed" || fleetStatus === "killed";
+            const res = terminal && residuals
+                ? {
+                    ...(residuals.usage ? { usage: residuals.usage } : {}),
+                    ...(residuals.stoppedBy ? { stoppedBy: residuals.stoppedBy } : {}),
+                    ...(residuals.transcriptId ? { transcriptId: residuals.transcriptId } : {}),
+                }
+                : {};
+            bus.publishTask({ id: run.runId, status: fleetStatus, tokens, elapsedMs: Date.now() - startedAt, ...res });
             for (const cid of children)
                 bus.removeTask(cid);
             children.clear();
             childStartedAt.clear();
             childByToolCall.clear();
-            if (fleetStatus === "completed" || fleetStatus === "failed" || fleetStatus === "killed") {
+            if (terminal) {
                 bus.removeTask(run.runId);
             }
         },
     };
 }
+export function fleetRunResiduals(result) {
+    if (!result)
+        return {};
+    const s = result.stats;
+    const usage = s
+        ? {
+            ...(typeof s.tokens === "number" ? { totalTokens: s.tokens } : {}),
+            ...(typeof s.turns === "number" ? { turns: s.turns } : {}),
+            ...(typeof s.toolCalls === "number" ? { toolUses: s.toolCalls } : {}),
+            ...(typeof s.costMicroUsd === "number" ? { costMicroUsd: s.costMicroUsd } : {}),
+        }
+        : {};
+    return {
+        ...(Object.keys(usage).length > 0 ? { usage } : {}),
+        ...(result.errorCode === "cancelled" ? { stoppedBy: "user" } : {}),
+        ...(result.sessionId ? { transcriptId: result.sessionId } : {}),
+    };
+}
 export function fleetBackgroundChildPublisher(bus, log) {
     if (!bus)
         return () => undefined;
@@ -325,7 +351,25 @@ export function fleetBackgroundChildPublisher(bus, log) {
             return;
         }
         const status = e.status === "completed" ? "completed" : e.status === "killed" ? "killed" : "failed";
-        bus.publishTask({ id: e.taskId, ...rowTags(m), status });
+        bus.publishTask({
+            id: e.taskId, ...rowTags(m), status,
+            ...(e.stoppedBy ? { stoppedBy: e.stoppedBy } : {}),
+            ...(e.resumable !== undefined ? { resumable: e.resumable } : {}),
+            ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}),
+            ...(e.editedFiles !== undefined ? { editedFiles: e.editedFiles.slice(0, 100).map((f) => ({ path: redactSecrets(f.path), edits: f.edits })) } : {}),
+            ...(e.usage
+                ? {
+                    usage: {
+                        ...(e.usage.totalTokens !== undefined ? { totalTokens: e.usage.totalTokens } : {}),
+                        ...(e.usage.toolUses !== undefined ? { toolUses: e.usage.toolUses } : {}),
+                        ...(e.usage.durationMs !== undefined ? { durationMs: e.usage.durationMs } : {}),
+                        ...(e.usage.tokens !== undefined ? { tokens: e.usage.tokens } : {}),
+                        ...(e.usage.turns !== undefined ? { turns: e.usage.turns } : {}),
+                        ...(e.usage.costMicroUsd !== undefined ? { costMicroUsd: e.usage.costMicroUsd } : {}),
+                    },
+                }
+                : {}),
+        });
         bus.removeTask(e.taskId);
         if (m.aliasUuid) {
             const tail = ` ${m.aliasUuid}`;

package/dist/http/server.d.ts

@@ -221,6 +221,7 @@ export interface TaskRequestBody {
         toolsDelta?: boolean;
     };
     forwardSubagentEvents?: boolean;
+    scratchpadDir?: string;
     retainSubagentSessions?: boolean | {
         ttlMs?: number;
         max?: number;

package/dist/http/server.js

@@ -21,7 +21,7 @@ import { runInBackground, evictIfConflict, stripCheckpointToken, resumeAtHttpSta
 import { looksLikeJwt } from "../auth-bridge.js";
 import { redactSteerIn, STEER_IN_MAX_CHARS, STEER_IN_MAX_REQUEST_CHARS } from "../orchestration/workflow-agent-steer.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationFoldKey, taskNotificationStreamKey, NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
-import { fleetRunPublisher, fleetRunLabels } from "../fleet/fleet-bus.js";
+import { fleetRunPublisher, fleetRunLabels, fleetRunResiduals } from "../fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "../fleet/subagent-tail-bus.js";
 import { RateLimiter } from "../observability/rate-limit.js";
 import { withPrincipal } from "../observability/principal-context.js";
@@ -679,6 +679,7 @@ export function createHttpServer(deps) {
                 toolOutput: true,
                 messageIdentity: true,
                 forwardSubagentEvents: true,
+                scratchpadDir: true,
                 subagentSteer: Boolean(deps.subagentSteerRegistry) && Boolean(deps.runStore),
                 subagentResume: Boolean(deps.subagentSteerRegistry) && Boolean(deps.runStore),
                 taskSettings: { permissions: true, permissionMode: true, model: true, outputStyle: true, env: false, hooks: deps.config.requirePrincipal !== true },
@@ -853,8 +854,12 @@ export function createHttpServer(deps) {
                     return;
                 }
                 streamTaskId = earlyDurableTid;
+                let usageKey;
                 streamDetached = detachOnDisconnect;
                 sseHeaders(res, earlyDurableTid ? { "x-task-id": earlyDurableTid } : undefined);
+                if (earlyDurableTid) {
+                    res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", taskId: earlyDurableTid, ...(prepared.spec.sessionId ? { sessionId: prepared.spec.sessionId } : {}) })}\n\n`);
+                }
                 const ac = new AbortController();
                 if (prepared.spec.sessionId)
                     markChildrenStoppedByUserOnAbort(ac.signal, prepared.spec.sessionId, prepared.auth?.principal);
@@ -921,6 +926,9 @@ export function createHttpServer(deps) {
                             const rs = deps.runStore;
                             const tid = durableTaskId;
                             ledgerSink = createLedgerSink({ appendEvent: (seq, type, data) => rs.appendEvent(tid, seq, type, data), persistThinking: deps.config.traceThinking });
+                            usageKey = prepared.spec.sessionId;
+                            if (usageKey)
+                                deps.modelUsage?.register(usageKey);
                         }
                         if (deps.checkpointStore && prepared.spec.sessionId) {
                             await deps.checkpointStore.putCtx(prepared.spec.sessionId, { body: prepared.body, memoryScope: prepared.auth?.memoryScope });
@@ -961,11 +969,11 @@ export function createHttpServer(deps) {
                             throw e;
                         }
                         let fleetSettled = false;
-                        const settleFleet = (status) => {
+                        const settleFleet = (status, residuals) => {
                             if (fleetSettled)
                                 return;
                             fleetSettled = true;
-                            fleetPub?.onTerminal(status);
+                            fleetPub?.onTerminal(status, residuals);
                         };
                         let liveStreamRef;
                         const subagentHandleEvictions = [];
@@ -1069,16 +1077,25 @@ export function createHttpServer(deps) {
                                             }
                                             finalizeTaskResult(ev.result, principal, prepared.spec.objective, prepared.spec.sessionId);
                                             putRewindAnchor();
-                                            settleFleet(finalResult?.status ?? "completed");
+                                            settleFleet(finalResult?.status ?? "completed", fleetRunResiduals(finalResult));
                                             if (ledgerSink && finalResult) {
+                                                if (usageKey && deps.modelUsage && deps.runStore && durableTaskId) {
+                                                    const rs2 = deps.runStore;
+                                                    const tid2 = durableTaskId;
+                                                    const fr = finalResult;
+                                                    finalResult = await attachModelUsage(fr, { append: ledgerSink.append, getEvents: (_id, after) => rs2.getEvents(tid2, after), modelUsage: deps.modelUsage, taskId: usageKey }).catch(() => fr);
+                                                }
                                                 await ledgerSink.onDone(finalResult);
                                                 ledgerTerminal = true;
                                             }
                                             res.write(`data: ${JSON.stringify({ ...ev, result: finalResult })}\n\n`);
                                             continue;
                                         }
-                                        if (ledgerSink)
+                                        if (ledgerSink) {
                                             await ledgerSink.onEvent(ev);
+                                            if (ev.type === "turn_end" && usageKey)
+                                                await appendModelUsageDelta(ledgerSink.append, deps.modelUsage, usageKey);
+                                        }
                                         fleetPub?.onEvent(ev);
                                         if (ev.type === "status")
                                             deps.metrics?.inc("brain_retry_total", { phase: String(ev.phase) });
@@ -1164,7 +1181,16 @@ export function createHttpServer(deps) {
                             }
                             const withApproval = () => approvalCtx && deps.toolApproval ? deps.toolApproval.runWithContext(approvalCtx, withQuestion) : withQuestion();
                             await (deps.sendUserFile
-                                ? deps.sendUserFile.runWithContext({ taskId: askTaskId, emit: async (f) => void (await emitAsk(f)) }, withApproval)
+                                ? deps.sendUserFile.runWithContext({
+                                    taskId: askTaskId,
+                                    emit: async (f) => {
+                                        void (await emitAsk(f));
+                                        if (ledgerSink) {
+                                            const { type, ...rest } = f;
+                                            await ledgerSink.append(type, rest).catch(() => undefined);
+                                        }
+                                    },
+                                }, withApproval)
                                 : withApproval());
                             if (durableTaskId && deps.runStore) {
                                 if (finalResult?.status === "suspended" && deps.checkpointStore)
@@ -1232,7 +1258,7 @@ export function createHttpServer(deps) {
                                                 await ledgerSink.onDone(finalResult).catch(() => undefined);
                                             }
                                             await deps.runStore.setTerminal(durableTaskId, finalResult.status, finalResult, finalResult.errorMessage ?? null);
-                                            settleFleet(finalResult.status);
+                                            settleFleet(finalResult.status, fleetRunResiduals(finalResult));
                                         }
                                         else if (ac.signal.aborted) {
                                             const err = "stream aborted before completion (run cancelled)";
@@ -1271,6 +1297,8 @@ export function createHttpServer(deps) {
                 finally {
                     uncountedBillableInflight--;
                     clearInterval(hb);
+                    if (usageKey)
+                        deps.modelUsage?.clear(usageKey);
                 }
                 if (!ranLive && resp && !res.writableEnded) {
                     res.write(`data: ${JSON.stringify({ type: "done", result: resp.body, replay: true })}\n\n`);
@@ -2163,7 +2191,17 @@ export function createHttpServer(deps) {
                 });
                 return;
             }
-            sendJson(res, 200, { taskId: runId, target, content: out.content, output: out.details });
+            const g14 = (() => {
+                const d = out.details;
+                if (!d || d.error !== undefined || d.retrieval_status === "not_ready")
+                    return {};
+                if (d.type === "background_bash")
+                    return { cursorSemantics: d.details && "bytesDroppedBeforeCursor" in d.details ? "cursor" : "full" };
+                if (d.type === "monitor" || d.type === "background_agent")
+                    return { cursorSemantics: "full" };
+                return {};
+            })();
+            sendJson(res, 200, { taskId: runId, target, content: out.content, output: out.details, ...g14 });
             return;
         }
         const subVerbMatch = req.method === "POST" ? (RUN_SUBAGENT_STEER_RE.exec(url) ?? RUN_SUBAGENT_RESUME_RE.exec(url)) : null;
@@ -5078,11 +5116,11 @@ export function createHttpServer(deps) {
             ? fleetRunPublisher(deps.fleetBus, { runId: taskId, scope: fleetScope, rootTaskId: sessionId, ...fleetRunLabels(resumeObjective) })
             : undefined;
         let fleetSettled = false;
-        const settleFleet = (status) => {
+        const settleFleet = (status, residuals) => {
             if (fleetSettled)
                 return;
             fleetSettled = true;
-            fleetPub?.onTerminal(status);
+            fleetPub?.onTerminal(status, residuals);
         };
         let result;
         let reopenConfirmedPark = false;
@@ -5445,7 +5483,7 @@ export function createHttpServer(deps) {
             else
                 await deps.runStore.setTerminal(taskId, result.status, stripCheckpointToken(result), result.errorMessage ?? null);
         }
-        settleFleet(checkpointReopened ? "suspended" : result.status);
+        settleFleet(checkpointReopened ? "suspended" : result.status, fleetRunResiduals(result));
         return {
             status: 200,
             body: {

package/dist/main.js

@@ -21,7 +21,7 @@ import { createSendUserFileIssuer } from "./plugins/send-user-file.js";
 import { withLedgerRecording } from "./plugins/send-file-ledger.js";
 import { basename, resolve } from "node:path";
 import { stat as fsStat, readFile as fsReadFile } from "node:fs/promises";
-import { buildEnvFacts, egressForRemoteExec, ensureScratchpadDir, purgeScratchpadDir, sweepStaleScratchpads, resumeFactsForLane } from "./env-facts.js";
+import { acceptShellScratchpadDir, buildEnvFacts, egressForRemoteExec, ensureScratchpadDir, purgeScratchpadDir, sweepStaleScratchpads, resumeFactsForLane } from "./env-facts.js";
 import { normalizeSuggestNextPrompts, normalizeResilience, normalizeAttachments, normalizeResumeAtMode, resolveTaskLimits, taskAgentsSpecFragment, retainBackgroundProcessesFromBody, toolNameListFromBody, promptProfileFromBody } from "./spec-fields.js";
 import { createBrain, brainSummary } from "./brain.js";
 import { loadConfig, logConfigDiagnostics } from "./config.js";
@@ -499,6 +499,12 @@ async function main() {
     }
     else {
         memoryEngine = memoryEngineBackendFor(config);
+        if (memoryEngine && process.env.LOCAL_DATA_ROOT && !config.memoryEngineDir) {
+            logger.warn("memory_engine_dir_defaulted", {
+                root: memoryEngine.root,
+                hint: "LOCAL_DATA_ROOT is set but MEMORY_ENGINE_DIR is not — the memory engine is sharing the machine-wide default; set MEMORY_ENGINE_DIR to isolate it under your data root",
+            });
+        }
     }
     let rosterStore;
     {
@@ -2181,9 +2187,13 @@ async function main() {
                 effectiveSettings = Object.keys(rest2).length > 0 ? rest2 : undefined;
             }
             const hostSemanticsLane = config.remoteExec === undefined || config.remoteExec.provider === "host";
-            const scratchpadDir = hostSemanticsLane && auth?.sessionId
-                ? await ensureScratchpadDir(config.localDataRoot ?? localRoot, auth.sessionId)
-                : undefined;
+            const shellScratchpad = await acceptShellScratchpadDir(body.scratchpadDir, {
+                requirePrincipal: config.requirePrincipal,
+                hostSemanticsLane,
+                warn: (msg, meta) => logger.warn(msg, { ...(meta ?? {}), sessionId: auth?.sessionId ?? null }),
+            });
+            const scratchpadDir = shellScratchpad ??
+                (hostSemanticsLane && auth?.sessionId ? await ensureScratchpadDir(config.localDataRoot ?? localRoot, auth.sessionId) : undefined);
             if (effectiveSettings) {
                 const fsWriteGate = hostSemanticsLane
                     ? (() => {

package/dist/runs.d.ts

@@ -5,7 +5,7 @@ import type { Metrics } from "./observability/metrics.js";
 import type { ModelUsageTracker, PromptManifestTracker } from "./budget.js";
 import type { ElicitationCoordinator } from "./elicitation.js";
 import type { QuestionCoordinator } from "./question.js";
-import type { FleetRunPublisher } from "./fleet/fleet-bus.js";
+import { type FleetRunPublisher } from "./fleet/fleet-bus.js";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
 export declare function backgroundAgentOutput(registry: typeof defaultTaskRegistry, handle: string, access: {
     owner: string;

package/dist/runs.js

@@ -3,6 +3,7 @@ import { withPrincipal } from "./observability/principal-context.js";
 import { redactSecrets } from "./trace/redact.js";
 import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "./trace/project.js";
 import { createLedgerSink } from "./trace/ledger-sink.js";
+import { fleetRunResiduals } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
 export async function backgroundAgentOutput(registry, handle, access, agentStore) {
@@ -365,13 +366,16 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         legLive = false;
         if (fleetPublisher) {
             if (reached?.kind === "done")
-                fleetPublisher.onTerminal(reached.result.errorCode === "cancelled" ? "cancelled" : reached.result.status);
+                fleetPublisher.onTerminal(reached.result.errorCode === "cancelled" ? "cancelled" : reached.result.status, fleetRunResiduals(reached.result));
             else if (reached?.kind === "suspended")
                 fleetPublisher.onTerminal("suspended");
             else if (reached?.kind === "needs_review")
                 fleetPublisher.onTerminal("needs_review");
             else
-                fleetPublisher.onTerminal(cancelCtrl.signal.aborted ? "cancelled" : "failed");
+                fleetPublisher.onTerminal(cancelCtrl.signal.aborted ? "cancelled" : "failed", {
+                    ...(cancelCtrl.signal.aborted ? { stoppedBy: "user" } : {}),
+                    ...(spec.sessionId ? { transcriptId: spec.sessionId } : {}),
+                });
         }
         if (inflight?.get(taskId) === cancelCtrl)
             inflight.delete(taskId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "1.290.0",
+  "version": "1.291.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",