@acpus/runtime 0.1.0 → 0.2.1

package/dist/agent-telemetry.d.ts

@@ -0,0 +1,49 @@
+import type { AgentAttemptTelemetry, AgentAttemptTelemetryState, AgentContextUsage, AgentTelemetry } from "./types.js";
+export interface AgentTelemetryAccumulatorOptions {
+    attempt: number;
+    inputText: string;
+    inputArtifactRef?: string;
+    startedAt?: string;
+    now?: () => number;
+    previewEdgeBytes?: number;
+    maxToolCalls?: number;
+    flushIntervalMs?: number;
+    onTelemetry?: (attempt: AgentAttemptTelemetry) => void;
+}
+export declare class AgentTelemetryAccumulator {
+    private readonly attempt;
+    private readonly now;
+    private readonly previewEdgeBytes;
+    private readonly maxToolCalls;
+    private readonly flushIntervalMs;
+    private readonly onTelemetry?;
+    private readonly startedAt;
+    private readonly seenToolIds;
+    private readonly tools;
+    private partialLine;
+    private response;
+    private stopReason;
+    private latestContext;
+    private outputArtifactRef;
+    private lastPublishedAt;
+    private toolSeq;
+    private totalToolCallCount;
+    constructor(options: AgentTelemetryAccumulatorOptions);
+    private readonly input;
+    append(chunk: string): void;
+    flush(): void;
+    responseText(): string;
+    setResponseText(text: string): void;
+    finalStopReason(): string | undefined;
+    context(): AgentContextUsage | undefined;
+    setOutputArtifactRef(ref: string | undefined): void;
+    snapshot(state?: AgentAttemptTelemetryState, completedAt?: string): AgentAttemptTelemetry;
+    private parseLine;
+    private captureResult;
+    private captureTool;
+    private trimRecentTools;
+    private publish;
+}
+export declare function upsertAgentAttemptTelemetry(current: AgentTelemetry | undefined, attempt: AgentAttemptTelemetry): AgentTelemetry;
+export declare function latestAgentAttemptTelemetry(telemetry: AgentTelemetry | undefined): AgentAttemptTelemetry | undefined;
+//# sourceMappingURL=agent-telemetry.d.ts.map

package/dist/agent-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-telemetry.d.ts","sourceRoot":"","sources":["../src/agent-telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,0BAA0B,EAC1B,iBAAiB,EAEjB,cAAc,EAEf,MAAM,YAAY,CAAC;AAOpB,MAAM,WAAW,gCAAgC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACxD;AAED,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAA2C;IACxE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAC5D,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,iBAAiB,CAAqB;IAC9C,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,kBAAkB,CAAK;gBAEnB,OAAO,EAAE,gCAAgC;IAWrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IAEvC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ3B,KAAK,IAAI,IAAI;IAMb,YAAY,IAAI,MAAM;IAItB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAInC,eAAe,IAAI,MAAM,GAAG,SAAS;IAIrC,OAAO,IAAI,iBAAiB,GAAG,SAAS;IAIxC,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAInD,QAAQ,CAAC,KAAK,GAAE,0BAAsC,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,qBAAqB;IA0BpG,OAAO,CAAC,SAAS;IAoCjB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,WAAW;IAuCnB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,OAAO;CAOhB;AAMD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,cAAc,GAAG,SAAS,EACnC,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAMhB;AAED,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,cAAc,GAAG,SAAS,GAAG,qBAAqB,GAAG,SAAS,CAIpH"}

package/dist/agent-telemetry.js

@@ -0,0 +1,255 @@
+const DEFAULT_PREVIEW_EDGE_BYTES = 8 * 1024;
+const DEFAULT_MAX_TOOL_CALLS = 200;
+const DEFAULT_FLUSH_INTERVAL_MS = 1_000;
+const FINAL_TOOL_STATUSES = new Set(["completed", "failed", "cancelled"]);
+export class AgentTelemetryAccumulator {
+    attempt;
+    now;
+    previewEdgeBytes;
+    maxToolCalls;
+    flushIntervalMs;
+    onTelemetry;
+    startedAt;
+    seenToolIds = new Set();
+    tools = new Map();
+    partialLine = "";
+    response = "";
+    stopReason;
+    latestContext;
+    outputArtifactRef;
+    lastPublishedAt = 0;
+    toolSeq = 0;
+    totalToolCallCount = 0;
+    constructor(options) {
+        this.attempt = options.attempt;
+        this.now = options.now ?? Date.now;
+        this.previewEdgeBytes = options.previewEdgeBytes ?? DEFAULT_PREVIEW_EDGE_BYTES;
+        this.maxToolCalls = options.maxToolCalls ?? DEFAULT_MAX_TOOL_CALLS;
+        this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+        this.onTelemetry = options.onTelemetry;
+        this.startedAt = options.startedAt ?? new Date(this.now()).toISOString();
+        this.input = buildPreview(options.inputText, this.previewEdgeBytes, options.inputArtifactRef);
+    }
+    input;
+    append(chunk) {
+        if (chunk.length === 0)
+            return;
+        const text = this.partialLine + chunk;
+        const lines = text.split("\n");
+        this.partialLine = lines.pop() ?? "";
+        for (const line of lines)
+            this.parseLine(line);
+    }
+    flush() {
+        if (this.partialLine.trim().length > 0)
+            this.parseLine(this.partialLine);
+        this.partialLine = "";
+        this.publish("running", true);
+    }
+    responseText() {
+        return this.response;
+    }
+    setResponseText(text) {
+        this.response = text;
+    }
+    finalStopReason() {
+        return this.stopReason;
+    }
+    context() {
+        return this.latestContext;
+    }
+    setOutputArtifactRef(ref) {
+        this.outputArtifactRef = ref;
+    }
+    snapshot(state = "running", completedAt) {
+        const updatedAt = completedAt ?? new Date(this.now()).toISOString();
+        const recentCalls = [...this.tools.values()]
+            .sort((a, b) => b.lastSeq - a.lastSeq)
+            .map(({ lastSeq: _lastSeq, ...tool }) => tool);
+        return {
+            attempt: this.attempt,
+            state,
+            startedAt: this.startedAt,
+            updatedAt,
+            completedAt,
+            context: this.latestContext,
+            input: this.input,
+            output: this.response.length > 0
+                ? buildPreview(this.response, this.previewEdgeBytes, this.outputArtifactRef)
+                : this.outputArtifactRef
+                    ? buildPreview("", this.previewEdgeBytes, this.outputArtifactRef)
+                    : undefined,
+            tools: {
+                totalToolCallCount: this.totalToolCallCount,
+                droppedToolCallCount: Math.max(0, this.totalToolCallCount - recentCalls.length),
+                recentCalls
+            }
+        };
+    }
+    parseLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        const parsed = parseObject(trimmed);
+        if (!parsed)
+            return;
+        this.captureResult(parsed);
+        const update = extractUpdate(parsed);
+        if (!update)
+            return;
+        const kind = update.sessionUpdate;
+        if (kind === "agent_message_chunk") {
+            const text = readContentText(update.content);
+            if (text) {
+                this.response += text;
+                this.publish("running", false);
+            }
+            return;
+        }
+        if (kind === "usage_update") {
+            const used = readNonNegativeNumber(update.used);
+            const size = readNonNegativeNumber(update.size);
+            if (used !== undefined && size !== undefined) {
+                this.latestContext = { used, size, updatedAt: new Date(this.now()).toISOString() };
+                this.publish("running", false);
+            }
+            return;
+        }
+        if (isToolUpdate(update)) {
+            const changed = this.captureTool(update);
+            this.publish("running", changed);
+        }
+    }
+    captureResult(obj) {
+        const result = readRecord(obj.result);
+        if (typeof result?.stopReason === "string")
+            this.stopReason = result.stopReason;
+    }
+    captureTool(update) {
+        const toolCallId = readString(update.toolCallId);
+        if (!toolCallId)
+            return false;
+        const now = new Date(this.now()).toISOString();
+        const wasSeen = this.seenToolIds.has(toolCallId);
+        if (!wasSeen) {
+            this.seenToolIds.add(toolCallId);
+            this.totalToolCallCount += 1;
+        }
+        const previous = this.tools.get(toolCallId);
+        const status = readString(update.status);
+        const current = previous ?? {
+            toolCallId,
+            startedAt: now,
+            updatedAt: now,
+            lastSeq: 0
+        };
+        const statusChanged = status !== undefined && status !== previous?.status;
+        current.updatedAt = now;
+        current.lastSeq = ++this.toolSeq;
+        const title = readString(update.title);
+        const kind = readString(update.kind);
+        const toolName = readString(readRecord(readRecord(update._meta)?.claudeCode)?.toolName);
+        if (title)
+            current.title = title;
+        if (kind)
+            current.kind = kind;
+        if (toolName)
+            current.toolName = toolName;
+        if (status) {
+            current.status = status;
+            if (FINAL_TOOL_STATUSES.has(status))
+                current.completedAt = now;
+        }
+        this.tools.set(toolCallId, current);
+        this.trimRecentTools();
+        return !wasSeen || statusChanged || (status !== undefined && FINAL_TOOL_STATUSES.has(status));
+    }
+    trimRecentTools() {
+        if (this.tools.size <= this.maxToolCalls)
+            return;
+        const ordered = [...this.tools.entries()].sort((a, b) => b[1].lastSeq - a[1].lastSeq);
+        const keep = new Set(ordered.slice(0, this.maxToolCalls).map(([id]) => id));
+        for (const id of this.tools.keys()) {
+            if (!keep.has(id))
+                this.tools.delete(id);
+        }
+    }
+    publish(state, force) {
+        if (!this.onTelemetry)
+            return;
+        const now = this.now();
+        if (!force && now - this.lastPublishedAt < this.flushIntervalMs)
+            return;
+        this.lastPublishedAt = now;
+        this.onTelemetry(this.snapshot(state));
+    }
+}
+export function upsertAgentAttemptTelemetry(current, attempt) {
+    const previous = current?.attempts.filter((item) => item.attempt !== attempt.attempt) ?? [];
+    return {
+        currentAttempt: attempt.attempt,
+        attempts: [...previous, attempt].sort((a, b) => a.attempt - b.attempt)
+    };
+}
+export function latestAgentAttemptTelemetry(telemetry) {
+    if (!telemetry)
+        return undefined;
+    return telemetry.attempts.find((attempt) => attempt.attempt === telemetry.currentAttempt)
+        ?? telemetry.attempts[telemetry.attempts.length - 1];
+}
+function buildPreview(text, edgeBytes, artifactRef) {
+    const originalBytes = Buffer.byteLength(text);
+    const maxBytes = edgeBytes * 2;
+    if (originalBytes <= maxBytes) {
+        return { preview: text, truncated: false, originalBytes, headBytes: originalBytes, artifactRef };
+    }
+    const bytes = Buffer.from(text);
+    const head = bytes.subarray(0, edgeBytes).toString("utf8");
+    const tail = bytes.subarray(Math.max(edgeBytes, bytes.length - edgeBytes)).toString("utf8");
+    return {
+        preview: `${head}\n[acpus truncated: originalBytes=${originalBytes}]\n${tail}`,
+        truncated: true,
+        originalBytes,
+        headBytes: edgeBytes,
+        tailBytes: edgeBytes,
+        artifactRef
+    };
+}
+function parseObject(line) {
+    try {
+        return readRecord(JSON.parse(line));
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractUpdate(obj) {
+    return readRecord(readRecord(obj.params)?.update);
+}
+function isToolUpdate(update) {
+    const kind = update.sessionUpdate;
+    return kind === "tool_call" || kind === "tool_call_update";
+}
+function readContentText(value) {
+    if (typeof value === "string")
+        return value;
+    const record = readRecord(value);
+    if (!record)
+        return undefined;
+    if (typeof record.text === "string")
+        return record.text;
+    const nested = readRecord(record.content);
+    return typeof nested?.text === "string" ? nested.text : undefined;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function readNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function readRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+//# sourceMappingURL=agent-telemetry.js.map

package/dist/agent-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-telemetry.js","sourceRoot":"","sources":["../src/agent-telemetry.ts"],"names":[],"mappings":"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"}

package/dist/artifacts.d.ts

@@ -1,4 +1,20 @@
 import type { ArtifactRef } from "./types.js";
+export interface ParsedArtifactReference {
+    uri: string;
+    runId: string;
+    /** URI-encoded resolved Node Key as it appears in the artifact URI. */
+    encodedNodeKey: string;
+    /** Decoded (resolved) Node Key with slashes (e.g. "workflow/step-a"). */
+    nodeKey: string;
+    filename: string;
+}
+export declare const ArtifactReferences: {
+    make(runId: string, nodeKey: string, filename: string): ArtifactRef;
+    parse(uri: string): ParsedArtifactReference;
+    tryParse(uri: string): ParsedArtifactReference | undefined;
+    rewriteRunId(uri: string, fromRunId: string, toRunId: string): string;
+    resolvePath(baseDir: string, uri: string, isUnsafeRunId: (runId: string) => boolean): string | undefined;
+};
 /**
  * Local filesystem artifact store under .acpus/state/runs/<run_id>/artifacts/.
  * Artifact URIs follow the format: artifact://runs/<runId>/nodes/<nodeKey>/<filename>
@@ -25,6 +41,5 @@ export declare class ArtifactStore {
     /** Parse an artifact URI into its components. */
     parseArtifactRef(uri: string): ArtifactRef;
     private nodeDir;
-    private makeRef;
 }
 //# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,CAAC,EAAE,MAAM;IAI5B;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW;IAa9F;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW;IAQrE,qEAAqE;IACrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW;IAQ/F,qCAAqC;IACrC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAM9D,yCAAyC;IACzC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE;IASnD,iDAAiD;IACjD,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAqB1C,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,OAAO;CAKhB"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,kBAAkB;gBACjB,MAAM,WAAW,MAAM,YAAY,MAAM,GAAG,WAAW;eAOxD,MAAM,GAAG,uBAAuB;kBA2B7B,MAAM,GAAG,uBAAuB,GAAG,SAAS;sBAQxC,MAAM,aAAa,MAAM,WAAW,MAAM,GAAG,MAAM;yBAMhD,MAAM,OAAO,MAAM,iBAAiB,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,MAAM,GAAG,SAAS;CAmBzG,CAAC;AAEF;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,CAAC,EAAE,MAAM;IAI5B;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW;IAa9F;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW;IAQrE,qEAAqE;IACrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW;IAQ/F,qCAAqC;IACrC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAM9D,yCAAyC;IACzC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE;IASnD,iDAAiD;IACjD,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAO1C,OAAO,CAAC,OAAO;CAIhB"}

package/dist/artifacts.js

@@ -1,6 +1,73 @@
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { encodeNodeKeyForDir } from "./keys.js";
+const ARTIFACT_URI_PREFIX = "artifact://runs/";
+export const ArtifactReferences = {
+    make(runId, nodeKey, filename) {
+        validateArtifactFilename(filename);
+        const encodedNodeKey = encodeURIComponent(nodeKey);
+        const uri = `${ARTIFACT_URI_PREFIX}${runId}/nodes/${encodedNodeKey}/${filename}`;
+        return { uri, runId, nodeKey, filename };
+    },
+    parse(uri) {
+        if (!uri.startsWith(ARTIFACT_URI_PREFIX)) {
+            throw new Error(`Invalid artifact URI: ${uri}`);
+        }
+        const parts = uri.slice(ARTIFACT_URI_PREFIX.length).split("/");
+        if (parts.length !== 4 || parts[1] !== "nodes") {
+            throw new Error(`Invalid artifact URI format: ${uri}`);
+        }
+        const runId = parts[0];
+        const encodedNodeKey = parts[2];
+        const filename = parts[3];
+        if (!runId || !encodedNodeKey || !filename) {
+            throw new Error(`Invalid artifact URI format: ${uri}`);
+        }
+        let nodeKey;
+        try {
+            nodeKey = decodeURIComponent(encodedNodeKey);
+        }
+        catch {
+            throw new Error(`Invalid artifact URI format: ${uri}`);
+        }
+        return { uri, runId, encodedNodeKey, nodeKey, filename };
+    },
+    tryParse(uri) {
+        try {
+            return this.parse(uri);
+        }
+        catch {
+            return undefined;
+        }
+    },
+    rewriteRunId(uri, fromRunId, toRunId) {
+        const ref = this.tryParse(uri);
+        if (!ref || ref.runId !== fromRunId)
+            return uri;
+        return `${ARTIFACT_URI_PREFIX}${toRunId}/nodes/${ref.encodedNodeKey}/${ref.filename}`;
+    },
+    resolvePath(baseDir, uri, isUnsafeRunId) {
+        const ref = this.tryParse(uri);
+        if (!ref || isUnsafeRunId(ref.runId))
+            return undefined;
+        if (!isSafeEncodedNodeKey(ref.encodedNodeKey) || !isSafeUriPathSegment(ref.filename))
+            return undefined;
+        try {
+            validateArtifactFilename(ref.filename);
+        }
+        catch {
+            return undefined;
+        }
+        const safeNodeDir = encodeNodeKeyForDir(ref.nodeKey);
+        if (!isSafeUriPathSegment(safeNodeDir))
+            return undefined;
+        const runDir = join(baseDir, ref.runId);
+        const resolved = resolve(join(runDir, "artifacts", safeNodeDir, ref.filename));
+        if (!isPathAtOrBelow(resolved, runDir))
+            return undefined;
+        return resolved;
+    }
+};
 /**
  * Local filesystem artifact store under .acpus/state/runs/<run_id>/artifacts/.
  * Artifact URIs follow the format: artifact://runs/<runId>/nodes/<nodeKey>/<filename>
@@ -15,33 +82,33 @@ export class ArtifactStore {
      * Returns the ArtifactRef for the written file.
      */
     write(runId, nodeKey, filename, content) {
-        validateArtifactFilename(filename);
+        const ref = ArtifactReferences.make(runId, nodeKey, filename);
         const dir = this.nodeDir(runId, nodeKey);
         mkdirSync(dir, { recursive: true });
         const filePath = join(dir, filename);
         const tmpPath = filePath + ".tmp";
         writeFileSync(tmpPath, content);
         renameSync(tmpPath, filePath);
-        return this.makeRef(runId, nodeKey, filename);
+        return ref;
     }
     /**
      * Create or truncate an artifact file and return its reference.
      * Used for artifacts that will be appended while an execution is still live.
      */
     create(runId, nodeKey, filename) {
-        validateArtifactFilename(filename);
+        const ref = ArtifactReferences.make(runId, nodeKey, filename);
         const dir = this.nodeDir(runId, nodeKey);
         mkdirSync(dir, { recursive: true });
         writeFileSync(join(dir, filename), "");
-        return this.makeRef(runId, nodeKey, filename);
+        return ref;
     }
     /** Append content to an existing artifact, creating it if needed. */
     append(runId, nodeKey, filename, content) {
-        validateArtifactFilename(filename);
+        const ref = ArtifactReferences.make(runId, nodeKey, filename);
         const dir = this.nodeDir(runId, nodeKey);
         mkdirSync(dir, { recursive: true });
         appendFileSync(join(dir, filename), content);
-        return this.makeRef(runId, nodeKey, filename);
+        return ref;
     }
     /** Read an artifact file content. */
     read(runId, nodeKey, filename) {
@@ -56,37 +123,18 @@ export class ArtifactStore {
             return [];
         return readdirSync(dir)
             .filter((f) => !f.endsWith(".tmp"))
-            .map((filename) => this.makeRef(runId, nodeKey, filename));
+            .map((filename) => ArtifactReferences.make(runId, nodeKey, filename));
     }
     /** Parse an artifact URI into its components. */
     parseArtifactRef(uri) {
-        const prefix = "artifact://runs/";
-        if (!uri.startsWith(prefix)) {
-            throw new Error(`Invalid artifact URI: ${uri}`);
-        }
-        const rest = uri.slice(prefix.length);
-        // Format: <runId>/nodes/<nodeKey>/<filename>
-        // nodeKey may contain : but not /
-        const parts = rest.split("/");
-        if (parts.length < 4 || parts[1] !== "nodes") {
-            throw new Error(`Invalid artifact URI format: ${uri}`);
-        }
-        const runId = parts[0];
-        // Everything between "nodes/" and the last segment is the nodeKey
-        const filename = parts[parts.length - 1];
-        const nodeKey = parts.slice(2, parts.length - 1).join("/");
-        return { uri, runId, nodeKey, filename };
+        const ref = ArtifactReferences.parse(uri);
+        return { uri: ref.uri, runId: ref.runId, nodeKey: ref.nodeKey, filename: ref.filename };
     }
     // ─── Internal helpers ──────────────────────────────────────────
     nodeDir(runId, nodeKey) {
         const safeKey = encodeNodeKeyForDir(nodeKey);
         return join(this.baseDir, runId, "artifacts", safeKey);
     }
-    makeRef(runId, nodeKey, filename) {
-        const safeKey = encodeNodeKeyForDir(nodeKey);
-        const uri = `artifact://runs/${runId}/nodes/${safeKey}/${filename}`;
-        return { uri, runId, nodeKey, filename };
-    }
 }
 /** Validate that an artifact filename has no path traversal or separator characters. */
 function validateArtifactFilename(filename) {
@@ -94,4 +142,19 @@ function validateArtifactFilename(filename) {
         throw new Error(`Invalid artifact filename: ${filename}`);
     }
 }
+function isSafeUriPathSegment(segment) {
+    return Boolean(segment) && !segment.split(/[/:]/).some((part) => part === "" || part === "." || part === "..");
+}
+function isSafeEncodedNodeKey(encodedNodeKey) {
+    return (Boolean(encodedNodeKey) &&
+        !encodedNodeKey.includes("/") &&
+        !encodedNodeKey.includes("\\") &&
+        !encodedNodeKey.includes(":") &&
+        encodedNodeKey !== "." &&
+        encodedNodeKey !== "..");
+}
+function isPathAtOrBelow(path, basePath) {
+    const normalizedBase = resolve(basePath);
+    return path === normalizedBase || path.startsWith(`${normalizedBase}/`);
+}
 //# sourceMappingURL=artifacts.js.map

package/dist/artifacts.js.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/attempt-artifacts.d.ts

@@ -0,0 +1,35 @@
+import { ArtifactStore } from "./artifacts.js";
+import type { AgentAttemptTelemetry } from "./types.js";
+export interface AgentAttemptFinalArtifacts {
+    responseText?: string;
+    stderr?: string;
+    diagnostics?: string[];
+}
+export interface AgentAttemptStartArtifacts {
+    artifactRefs: string[];
+    promptRef: string;
+    rawAcpDebugRef?: string;
+}
+export interface AgentAttemptFinalArtifactRefs {
+    artifactRefs: string[];
+    responseRef?: string;
+    stderrRef?: string;
+}
+/**
+ * Owns runtime artifact naming and lifecycle rules for executable node attempts.
+ */
+export declare class AttemptArtifactRecorder {
+    private readonly artifactStore;
+    constructor(artifactStore: ArtifactStore);
+    startAgentAttempt(runId: string, nodeKey: string, attemptNo: number, prompt: string, options?: {
+        rawAcpDebug?: boolean;
+    }): AgentAttemptStartArtifacts;
+    appendAgentRawAcpDebug(runId: string, nodeKey: string, attemptNo: number, chunk: string): void;
+    finalizeAgentAttempt(runId: string, nodeKey: string, attemptNo: number, content: AgentAttemptFinalArtifacts): AgentAttemptFinalArtifactRefs;
+    writeAgentTelemetry(runId: string, nodeKey: string, attemptNo: number, telemetry: AgentAttemptTelemetry): string;
+    writeProgramArtifacts(runId: string, nodeKey: string, stdout: string, stderr: string): string[];
+    mergeAttemptRefs(target: string[], refs: string[] | undefined): void;
+    private mergeStderrDiagnostics;
+    private agentAttemptPrefix;
+}
+//# sourceMappingURL=attempt-artifacts.d.ts.map

package/dist/attempt-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-artifacts.d.ts","sourceRoot":"","sources":["../src/attempt-artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,0BAA0B;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,6BAA6B;IAC5C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,uBAAuB;IACtB,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,aAAa;IAEzD,iBAAiB,CACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAO,GACtC,0BAA0B;IAa7B,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAI9F,oBAAoB,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,0BAA0B,GAClC,6BAA6B;IAiBhC,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,qBAAqB,GAAG,MAAM;IAShH,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAM/F,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI;IAYpE,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,kBAAkB;CAG3B"}