@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/attachment-zip.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ZIP validation and decompression for attachment archives — the byte-level
+ * half of an `extract` attachment, shared by every writer of one.
+ *
+ * Security model: attachments are untrusted user uploads. Archives are parsed
+ * from the central directory — the format's authoritative index — via the
+ * shared structural layer (@stigmer/zip-structure; issue #567, which killed
+ * the earlier local-header walk: it silently truncated stored streaming
+ * entries and rejected Go-default archives outright). Every entry is
+ * validated for path traversal, zip bombs, and format integrity BEFORE any
+ * extraction occurs, and because the central directory's sizes are
+ * declarations an attacker controls, decompression re-enforces them: an
+ * entry whose actual output disagrees with its declared size aborts the
+ * extraction.
+ *
+ * Error model: fail-hard through {@link AttachmentValidationError}. An
+ * archive that fails any check aborts the whole attachment resolution and
+ * propagates a descriptive, user-fixable message. This is deliberately the
+ * OPPOSITE policy from the skill-artifact reader (`zip-extract.ts`,
+ * non-fatal empty return): skill artifacts were structurally vouched for by
+ * the push gates, attachments never are.
+ *
+ * Validation and decompression share one record ({@link ValidatedZipEntry},
+ * still carrying its payload slice), so parsing happens exactly once and
+ * "the manifest promised a file extraction cannot find" is unrepresentable.
+ * The WRITE of an extracted entry is the caller's: the attachment resolver
+ * writes under the session's platform dir (`attachment-resolver.ts`), the
+ * one caller since #1096 retired the native injector. Moved here from that
+ * injector in the same PR so the guards have one home.
+ */
+export declare const MAX_ZIP_FILES = 1000;
+export declare const MAX_ZIP_EXTRACTED_SIZE: number;
+export interface ZipEntryInfo {
+    readonly relativePath: string;
+    readonly uncompressedSize: number;
+}
+/**
+ * A validated file entry, still carrying its payload slice. Validation and
+ * extraction share these records — parsing happens exactly once, so "the
+ * manifest promised a file extraction cannot find" is unrepresentable
+ * (the old two-walker design silently skipped such entries).
+ */
+export interface ValidatedZipEntry extends ZipEntryInfo {
+    readonly compressionMethod: number;
+    readonly compressedData: Uint8Array;
+}
+/** An archive the user handed us cannot be safely extracted; the reason is theirs to fix. */
+export declare class AttachmentValidationError extends Error {
+    readonly attachmentFilename: string;
+    readonly reason: string;
+    constructor(attachmentFilename: string, reason: string);
+}
+/**
+ * Validate a ZIP archive for safe extraction. Returns the manifest of
+ * file entries (directories excluded) if the archive passes all checks.
+ *
+ * Security checks enforced:
+ * 1. Valid ZIP format (readable central directory; fail-hard, see module doc)
+ * 2. No absolute paths (entries starting with / or \)
+ * 3. No path traversal (.. components)
+ * 4. No null bytes in filenames
+ * 5. No duplicate entry paths (a contradictory manifest)
+ * 6. Only supported compression methods (stored, deflate) — checked here
+ *    so an unsupported entry can never abort extraction after earlier
+ *    entries were already written
+ * 7. Non-empty archive (at least one file entry)
+ * 8. File count within limits (max 1000)
+ * 9. Total declared uncompressed size within limits (max 100 MB) —
+ *    declarations are re-enforced against actual output at decompression
+ */
+export declare function validateZipForExtraction(zipData: Buffer, sourceFilename: string): ZipEntryInfo[];
+/** The same checks as {@link validateZipForExtraction}, keeping each entry's payload for the extraction that follows. */
+export declare function parseAndValidateZip(zipData: Buffer, sourceFilename: string): ValidatedZipEntry[];
+/**
+ * Decompress a validated entry, enforcing its declared uncompressed size.
+ *
+ * The size cap in parseAndValidateZip budgets *declared* sizes, which the
+ * archive author controls — a crafted archive can declare 1 KB and inflate
+ * to gigabytes. Enforcement is therefore two-sided and fail-hard: inflation
+ * aborts the moment output exceeds the declaration, and an undershoot (or a
+ * stored payload whose length disagrees) fails too, because a manifest that
+ * misdescribes its own contents is exactly the corrupt-input class this
+ * module must never extract from.
+ */
+export declare function decompressEntry(entry: ValidatedZipEntry, sourceFilename: string): Promise<Buffer>;

package/dist/shared/attachment-zip.js

@@ -0,0 +1,185 @@
+/**
+ * ZIP validation and decompression for attachment archives — the byte-level
+ * half of an `extract` attachment, shared by every writer of one.
+ *
+ * Security model: attachments are untrusted user uploads. Archives are parsed
+ * from the central directory — the format's authoritative index — via the
+ * shared structural layer (@stigmer/zip-structure; issue #567, which killed
+ * the earlier local-header walk: it silently truncated stored streaming
+ * entries and rejected Go-default archives outright). Every entry is
+ * validated for path traversal, zip bombs, and format integrity BEFORE any
+ * extraction occurs, and because the central directory's sizes are
+ * declarations an attacker controls, decompression re-enforces them: an
+ * entry whose actual output disagrees with its declared size aborts the
+ * extraction.
+ *
+ * Error model: fail-hard through {@link AttachmentValidationError}. An
+ * archive that fails any check aborts the whole attachment resolution and
+ * propagates a descriptive, user-fixable message. This is deliberately the
+ * OPPOSITE policy from the skill-artifact reader (`zip-extract.ts`,
+ * non-fatal empty return): skill artifacts were structurally vouched for by
+ * the push gates, attachments never are.
+ *
+ * Validation and decompression share one record ({@link ValidatedZipEntry},
+ * still carrying its payload slice), so parsing happens exactly once and
+ * "the manifest promised a file extraction cannot find" is unrepresentable.
+ * The WRITE of an extracted entry is the caller's: the attachment resolver
+ * writes under the session's platform dir (`attachment-resolver.ts`), the
+ * one caller since #1096 retired the native injector. Moved here from that
+ * injector in the same PR so the guards have one home.
+ */
+import { createInflateRaw } from "node:zlib";
+import { posix } from "node:path";
+import { EOCD_MIN_SIZE, parseZipStructure, } from "@stigmer/zip-structure";
+// ── Constants ────────────────────────────────────────────────────────
+export const MAX_ZIP_FILES = 1000;
+export const MAX_ZIP_EXTRACTED_SIZE = 100 * 1024 * 1024; // 100 MB
+// ── Errors ───────────────────────────────────────────────────────────
+/** An archive the user handed us cannot be safely extracted; the reason is theirs to fix. */
+export class AttachmentValidationError extends Error {
+    attachmentFilename;
+    reason;
+    constructor(attachmentFilename, reason) {
+        super(`Attachment '${attachmentFilename}': ${reason}`);
+        this.name = "AttachmentValidationError";
+        this.attachmentFilename = attachmentFilename;
+        this.reason = reason;
+    }
+}
+// ── ZIP Validation (pure functions) ──────────────────────────────────
+/**
+ * Validate a ZIP archive for safe extraction. Returns the manifest of
+ * file entries (directories excluded) if the archive passes all checks.
+ *
+ * Security checks enforced:
+ * 1. Valid ZIP format (readable central directory; fail-hard, see module doc)
+ * 2. No absolute paths (entries starting with / or \)
+ * 3. No path traversal (.. components)
+ * 4. No null bytes in filenames
+ * 5. No duplicate entry paths (a contradictory manifest)
+ * 6. Only supported compression methods (stored, deflate) — checked here
+ *    so an unsupported entry can never abort extraction after earlier
+ *    entries were already written
+ * 7. Non-empty archive (at least one file entry)
+ * 8. File count within limits (max 1000)
+ * 9. Total declared uncompressed size within limits (max 100 MB) —
+ *    declarations are re-enforced against actual output at decompression
+ */
+export function validateZipForExtraction(zipData, sourceFilename) {
+    return parseAndValidateZip(zipData, sourceFilename).map(({ relativePath, uncompressedSize }) => ({ relativePath, uncompressedSize }));
+}
+/** The same checks as {@link validateZipForExtraction}, keeping each entry's payload for the extraction that follows. */
+export function parseAndValidateZip(zipData, sourceFilename) {
+    if (zipData.length < EOCD_MIN_SIZE) {
+        throw new AttachmentValidationError(sourceFilename, "not a valid ZIP archive (file too small)");
+    }
+    let structural;
+    try {
+        structural = parseZipStructure(zipData);
+    }
+    catch (err) {
+        throw new AttachmentValidationError(sourceFilename, `not a valid ZIP archive (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const entries = [];
+    const seenPaths = new Set();
+    let totalUncompressed = 0;
+    for (const entry of structural) {
+        if (entry.name.includes("\u0000")) {
+            throw new AttachmentValidationError(sourceFilename, "contains a filename with null bytes and cannot be safely extracted");
+        }
+        if (entry.isDirectory)
+            continue;
+        if (entry.name.startsWith("/") || entry.name.startsWith("\\")) {
+            throw new AttachmentValidationError(sourceFilename, `contains an absolute path entry and cannot be safely extracted: ${entry.name}`);
+        }
+        if (hasPathTraversal(entry.name)) {
+            throw new AttachmentValidationError(sourceFilename, `contains a path traversal entry and cannot be safely extracted: ${entry.name}`);
+        }
+        if (seenPaths.has(entry.name)) {
+            throw new AttachmentValidationError(sourceFilename, `contains duplicate entry '${entry.name}' and cannot be safely extracted`);
+        }
+        seenPaths.add(entry.name);
+        if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+            throw new AttachmentValidationError(sourceFilename, `entry '${entry.name}' uses unsupported compression method ${entry.compressionMethod}`);
+        }
+        entries.push({
+            relativePath: entry.name,
+            uncompressedSize: entry.uncompressedSize,
+            compressionMethod: entry.compressionMethod,
+            compressedData: entry.compressedData,
+        });
+        totalUncompressed += entry.uncompressedSize;
+    }
+    if (entries.length === 0) {
+        throw new AttachmentValidationError(sourceFilename, "is an empty ZIP archive (no file entries)");
+    }
+    if (entries.length > MAX_ZIP_FILES) {
+        throw new AttachmentValidationError(sourceFilename, `contains ${entries.length} files (limit: ${MAX_ZIP_FILES})`);
+    }
+    if (totalUncompressed > MAX_ZIP_EXTRACTED_SIZE) {
+        const sizeMb = (totalUncompressed / (1024 * 1024)).toFixed(1);
+        const limitMb = (MAX_ZIP_EXTRACTED_SIZE / (1024 * 1024)).toFixed(0);
+        throw new AttachmentValidationError(sourceFilename, `would extract to ${sizeMb} MB (limit: ${limitMb} MB)`);
+    }
+    return entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+// ── Decompression ────────────────────────────────────────────────────
+/**
+ * Decompress a validated entry, enforcing its declared uncompressed size.
+ *
+ * The size cap in parseAndValidateZip budgets *declared* sizes, which the
+ * archive author controls — a crafted archive can declare 1 KB and inflate
+ * to gigabytes. Enforcement is therefore two-sided and fail-hard: inflation
+ * aborts the moment output exceeds the declaration, and an undershoot (or a
+ * stored payload whose length disagrees) fails too, because a manifest that
+ * misdescribes its own contents is exactly the corrupt-input class this
+ * module must never extract from.
+ */
+export async function decompressEntry(entry, sourceFilename) {
+    const declared = entry.uncompressedSize;
+    if (entry.compressionMethod === 0) {
+        if (entry.compressedData.length !== declared) {
+            throw new AttachmentValidationError(sourceFilename, `entry '${entry.relativePath}' payload is ${entry.compressedData.length} bytes ` +
+                `but the archive declares ${declared} — corrupt or crafted archive`);
+        }
+        return Buffer.from(entry.compressedData);
+    }
+    // Deflate — the only other method parseAndValidateZip admits.
+    return new Promise((resolve, reject) => {
+        const inflate = createInflateRaw();
+        const chunks = [];
+        let produced = 0;
+        inflate.on("data", (chunk) => {
+            produced += chunk.length;
+            if (produced > declared) {
+                inflate.destroy();
+                reject(new AttachmentValidationError(sourceFilename, `entry '${entry.relativePath}' decompresses past its declared size of ` +
+                    `${declared} bytes — corrupt or crafted archive`));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        inflate.on("end", () => {
+            if (produced !== declared) {
+                reject(new AttachmentValidationError(sourceFilename, `entry '${entry.relativePath}' decompressed to ${produced} bytes ` +
+                    `but the archive declares ${declared} — corrupt or crafted archive`));
+                return;
+            }
+            resolve(Buffer.concat(chunks));
+        });
+        inflate.on("error", reject);
+        inflate.end(Buffer.from(entry.compressedData));
+    });
+}
+function hasPathTraversal(filePath) {
+    const normalized = posix.normalize(filePath);
+    if (normalized.startsWith("../") || normalized === "..")
+        return true;
+    const segments = filePath.split(/[/\\]/);
+    for (const seg of segments) {
+        if (seg === "..")
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=attachment-zip.js.map

package/dist/shared/attachment-zip.js.map

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

package/dist/shared/blueprint-resolver.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Resolves the agent blueprint of a turn: the agent spec the turn runs, the
+ * plugins it uses (the agent's and the session's), the saved agents it
+ * lists as subagents, and the merge of its skill refs with the session's
+ * own.
+ *
+ * The agent comes from the turn's stamp alone (status.agent_id and
+ * agent_version_hash), which the server records on every turn before it
+ * runs: from the session's pin at create, and from the session's pin on
+ * recover for a turn that carried none. The spec is that version's
+ * snapshot, read through getAgentVersion, so an author saving a new
+ * version while the turn is queued or running never changes what runs,
+ * and a session repointed to another agent afterwards never changes which
+ * agent this turn runs. A recorded version that no longer resolves (the
+ * agent was deleted, the run's person may no longer see it, a store fault)
+ * fails the turn naming the version: running the agent's current version
+ * would run, and record, something nobody asked for. A stamp naming an
+ * agent with no version runs that agent as it is now. The runner never
+ * walks the session to find an agent: the session's pin reaches the turn
+ * through the stamp, so there is one route to the agent and one writer of
+ * it.
+ *
+ * A turn whose stamp names no agent is the built-in assistant: `agent` is
+ * undefined, the instructions are empty (each harness's prompt builder
+ * substitutes the one built-in prompt, shared/builtin-assistant-prompt.ts),
+ * there are no subagents of its own, and the session's own plugins and
+ * skill refs are the whole tool set — the same merge with an empty agent
+ * side, so no consumer downstream needs an agent-less arm of its own.
+ *
+ * Plugins. The agent version's `plugins` and the session's are merged one
+ * entry per plugin (organization and slug), the session's reference winning
+ * (its version is the one the conversation chose); the server plans a run's
+ * values from the same merge (domain/run/run-plugins.ts). Each resolves
+ * like a skill reference, its version when set, else the installed one, at
+ * turn start. A listed plugin that cannot be read fails the turn naming it,
+ * as a conversation whose agent is gone does: running without it would run
+ * its tools, hooks and skills away silently. Each plugin's agents are the
+ * turn's plugin subagents, named `<plugin>:<agent>` (Claude Code's plugin
+ * subagents: the turn's tools narrowed by the plugin's own lists, the
+ * plugin's skills, and the model their file names where the engine lists
+ * it; harness/turn-context.ts).
+ *
+ * Subagents. Each saved agent the agent version lists in `subagents` is
+ * read at the version the agent pinned when it was saved
+ * (`getAgentByReference`, whose read the server authorizes as a `get` of
+ * that agent), so an edit to the subagent reaches this turn only once the
+ * parent is saved again. A subagent that cannot be read fails the turn
+ * naming it, as a plugin does. Its own plugins resolve through the same
+ * merge, after the conversation's: a plugin the conversation already lists
+ * is that one, at its version, so the server's plan for the run's values
+ * (domain/run/run-plugins.ts) is what runs. The turn builds each
+ * subagent's own context from them (harness/turn-context.ts
+ * `resolveSubagents`).
+ *
+ * Exclusion. A run's `excluded_plugin_ids` (set only by the server's
+ * evals, to run a case without the plugin it compares) leaves those
+ * plugins out of the turn wherever they come from: the agent's list, the
+ * session's, or a subagent's. Each is matched on the resolved plugin's id,
+ * since a reference may still name a plugin by slug alone, so a plugin
+ * left out is still read; it loads nothing into the turn. The server
+ * plans the run's values without the same plugins (domain/run/
+ * run-plugins.ts).
+ *
+ * A turn whose run carries the judge label is the built-in judge
+ * (builtin-judge.ts), whatever its stamp: the judge's code-defined spec is
+ * the agent, with id "" as the built-ins have, and the turn gets no plugin,
+ * skill ref or subagent, not even the session's own, so the judge can act
+ * on nothing in the conversation it grades.
+ *
+ * Workspace isolation: resolved workspace directories are validated to
+ * ensure they never point at the runner's own app directory. Paths
+ * containing runner-internal markers are rejected with a warning.
+ */
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { RunStatus } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import type { AgentSpec } from "@stigmer/apis/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { Plugin } from "@stigmer/apis/ai/stigmer/agentic/plugin/v1/api_pb";
+import type { Session } from "@stigmer/apis/ai/stigmer/agentic/session/v1/api_pb";
+import type { SessionSpec } from "@stigmer/apis/ai/stigmer/agentic/session/v1/spec_pb";
+import type { WorkspaceEntry } from "@stigmer/apis/ai/stigmer/agentic/session/v1/workspace_pb";
+import type { ApiResourceReference } from "@stigmer/apis/ai/stigmer/commons/apiresource/io_pb";
+export interface CloudRepo {
+    url: string;
+    startingRef?: string;
+}
+/** The agent a turn runs: its id, the version it recorded, and that version's spec. */
+export interface RunAgent {
+    readonly id: string;
+    /** Empty when the turn recorded no version (the agent runs as it is now). */
+    readonly versionHash: string;
+    readonly spec: AgentSpec;
+}
+/** The agent a turn recorded at create (RunStatus). */
+export type RecordedRunAgent = Pick<RunStatus, "agentId" | "agentVersionHash">;
+/** A plugin's agent as a turn runs it: Claude Code's plugin subagent. */
+export interface PluginSubagent {
+    /** `<plugin>:<agent>`. */
+    readonly name: string;
+    readonly description: string;
+    readonly instructions: string;
+    /** The plugin's own lists for it, in Claude Code's names; they narrow the turn's tools. */
+    readonly tools: readonly string[];
+    readonly disallowedTools: readonly string[];
+    /** The model its file names, as written; "" when it names none. */
+    readonly model: string;
+}
+/** A saved agent the turn's agent lists as a subagent, at the version its parent pinned. */
+export interface SavedSubagent {
+    /** Its name in the turn: its slug. */
+    readonly name: string;
+    readonly agentId: string;
+    readonly versionHash: string;
+    readonly spec: AgentSpec;
+    /** Its own plugins, each at the version the turn's merge resolved (the module header). */
+    readonly plugins: readonly Plugin[];
+}
+export interface ResolvedBlueprint {
+    /** The agent the turn runs; undefined for the built-in assistant. */
+    agent: RunAgent | undefined;
+    session: Session;
+    sessionSpec: SessionSpec;
+    instructions: string;
+    /** Each plugin's agents, as `<plugin>:<agent>`. */
+    pluginAgents: PluginSubagent[];
+    /** The saved agents the agent lists, in its order. */
+    subagents: SavedSubagent[];
+    /** The turn's plugins, each at the version it resolved to, in merge order. */
+    plugins: Plugin[];
+    mergedSkillRefs: ApiResourceReference[];
+    cloudRepos: CloudRepo[];
+}
+/**
+ * Resolve the full agent blueprint of a turn: the stamped agent (the module
+ * doc); a turn whose stamp names no agent is the built-in assistant; a run
+ * labelled as a judge's is the built-in judge.
+ */
+export declare function resolveBlueprint(client: StigmerClient, session: Session, recorded: RecordedRunAgent | undefined, runLabels: Readonly<Record<string, string>>, excludedPluginIds?: readonly string[]): Promise<ResolvedBlueprint>;
+/**
+ * Merge plugin references from the agent and the session, one per plugin
+ * by organization and id (or slug, for a reference written by name; an
+ * empty organization is the session's), the session's reference winning.
+ * A reference whose plugin was deleted is left out with a warning.
+ */
+export declare function mergePluginRefs(agentRefs: readonly ApiResourceReference[], sessionRefs: readonly ApiResourceReference[], org: string): ApiResourceReference[];
+/**
+ * The references that name a resource the turn can load. Every reference
+ * reaches the runner from the server, which names each by its target's
+ * current slug; one that holds an id and no slug names a resource that was
+ * deleted, and is left out with a warning, as a skill that cannot be read
+ * is. An unset reference names nothing.
+ */
+export declare function usableRefs(refs: readonly ApiResourceReference[], noun: string): ApiResourceReference[];
+/** A plugin's agents as the turn's plugin subagents, named `<plugin>:<agent>`, with the plugin's own tool lists and model. */
+export declare function pluginSubagents(plugin: Plugin): PluginSubagent[];
+/** `<plugin>:<agent>`, as Claude Code names a plugin's agent. */
+export declare function pluginAgentName(pluginName: string, agentName: string): string;
+/**
+ * Extract Cursor SDK-compatible repo descriptors from workspace entries.
+ *
+ * Maps Stigmer's GitRepoSource (url + branch) to the Cursor SDK's
+ * CloudAgentOptions.repos shape ({ url, startingRef? }). Only GitRepoSource
+ * entries produce output — LocalPathSource entries are silently skipped.
+ *
+ * Always computed (cheap iteration) but only consumed when mode is cloud.
+ */
+export declare function resolveCloudRepos(workspaceEntries: WorkspaceEntry[]): CloudRepo[];
+/**
+ * Merge skill refs from agent and session.
+ *
+ * Replicates session_context_merge.py::merge_skill_refs():
+ * - Union of both sets, deduplicated by slug: a skill mounts by its name
+ * - Session refs take precedence on collision (may have different version)
+ * - A reference whose skill was deleted is left out (usableRefs)
+ */
+export declare function mergeSkillRefs(agentRefs: ApiResourceReference[], sessionRefs: ApiResourceReference[]): ApiResourceReference[];