@tagma/sdk 0.6.4 → 0.6.6

package/dist/ports.js

@@ -0,0 +1,365 @@
+// ═══ Task ports: substitute / resolve / extract ═══
+//
+// One module, three concerns, all keyed on `task.ports`:
+//
+//   1. `substituteInputs(text, inputs)` — expand `{{inputs.<name>}}` in
+//      user-authored strings (command lines, prompts). Strict syntax, no
+//      arbitrary expressions — the placeholder is a thin pasteboard, not
+//      a templating engine. Unknown / undefined references render as empty
+//      string with a diagnostic that the caller can surface.
+//
+//   2. `resolveTaskInputs(task, upstreamOutputs, dependsOn)` — gather the
+//      values a task will consume from its direct upstreams. Matches by
+//      port name (or by explicit `from:`), applies defaults, coerces to
+//      the declared type, and classifies the result as ready / missing
+//      required / ambiguous. The engine calls this before a task starts
+//      and uses the classification to decide whether to block.
+//
+//   3. `extractTaskOutputs(ports, stdout, normalizedOutput)` — after a
+//      task succeeds, pull the declared output values from the task's
+//      output stream. Default strategy: find the last non-empty line that
+//      parses as a JSON object, and read each declared output name from
+//      it. Prefer `normalizedOutput` for AI tasks, fall back to raw
+//      stdout — command tasks only ever have stdout.
+//
+// Everything here is pure / deterministic so it can be reused by the CLI,
+// the editor (for preview/simulation), and the engine without side effects.
+// ─── Template substitution ────────────────────────────────────────────
+/**
+ * Matches `{{inputs.<identifier>}}` with optional whitespace inside the
+ * braces. The identifier is restricted to the same character set we use
+ * for task IDs (letter/underscore, then letters/digits/underscores) so
+ * accidental use of `{{inputs.foo.bar}}` fails loudly rather than
+ * silently producing garbage.
+ */
+const PLACEHOLDER_RE = /\{\{\s*inputs\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+/**
+ * Scan `text` for every `{{inputs.<name>}}` placeholder and return the
+ * set of referenced input names. Useful at validation time: the editor
+ * can cross-check that each placeholder has a corresponding declared
+ * port and flag typos before a run ever starts.
+ */
+export function extractInputReferences(text) {
+    const names = new Set();
+    for (const match of text.matchAll(PLACEHOLDER_RE)) {
+        names.add(match[1]);
+    }
+    return [...names];
+}
+/**
+ * Replace `{{inputs.<name>}}` placeholders in `text` with values from
+ * `inputs`. Coercion:
+ *   - string  → as-is
+ *   - number / boolean → `String(value)`
+ *   - null / undefined → empty string (name is also reported as unresolved)
+ *   - anything else (object, array, json port) → `JSON.stringify(value)`
+ *
+ * Values are substituted *verbatim* — quoting is the user's
+ * responsibility in the authored text. For command lines that interpolate
+ * user-provided strings, authors should wrap the placeholder in quotes:
+ *
+ *     weather.sh --city "{{inputs.city}}"
+ *
+ * That's a documented contract rather than a silent shell-escape, because
+ * silent escaping would hide the difference between `--city Shanghai` and
+ * `--flag $(echo pwned)` — both valid command fragments, one a bug, one a
+ * feature. Users know which they want; the engine doesn't.
+ */
+export function substituteInputs(text, inputs) {
+    const unresolved = new Set();
+    const out = text.replace(PLACEHOLDER_RE, (_full, name) => {
+        if (!(name in inputs)) {
+            unresolved.add(name);
+            return '';
+        }
+        const value = inputs[name];
+        if (value === null || value === undefined) {
+            unresolved.add(name);
+            return '';
+        }
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return String(value);
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            // Circular / unserializable — render a placeholder rather than
+            // throwing, and mark it unresolved so the caller can warn.
+            unresolved.add(name);
+            return '';
+        }
+    });
+    return { text: out, unresolved: [...unresolved] };
+}
+/**
+ * Resolve the input values for `task` from the outputs its direct
+ * upstreams produced.
+ *
+ * `upstreamOutputs` is keyed by fully-qualified task id and maps to the
+ * outputs that task published (its `TaskResult.outputs`). `dependsOn` is
+ * the already-qualified dependency list (from `DagNode.dependsOn`). When
+ * an upstream has no outputs entry (e.g. it didn't declare any or it
+ * failed), its entry may be missing — we just skip it during matching.
+ *
+ * Matching rules:
+ *   - If the input port has `from: "taskId.portName"` → look up that
+ *     specific upstream / port. Missing = unsatisfied.
+ *   - If it has `from: "portName"` (bare) → treat as explicit port name
+ *     but allow any upstream to provide it (useful when the user wants
+ *     to match by name but still be explicit about the intent).
+ *   - If no `from` → scan every upstream's outputs for a key matching
+ *     the input name. Zero hits = unsatisfied; 2+ hits across different
+ *     upstreams = ambiguous.
+ *
+ * The function never throws on config errors — every failure mode maps
+ * to a field of the `blocked` result so the engine can log a unified
+ * message and mark the task blocked.
+ */
+export function resolveTaskInputs(task, upstreamOutputs, dependsOn) {
+    const inputsDecl = task.ports?.inputs;
+    if (!inputsDecl || inputsDecl.length === 0) {
+        return { kind: 'ready', inputs: {}, missingOptional: [] };
+    }
+    const inputs = {};
+    const missingRequired = [];
+    const missingOptional = [];
+    const ambiguous = [];
+    const typeErrors = [];
+    for (const port of inputsDecl) {
+        const found = findUpstreamValue(port, upstreamOutputs, dependsOn);
+        if (found.kind === 'ambiguous') {
+            ambiguous.push({ port: port.name, producers: found.producers });
+            continue;
+        }
+        let value;
+        let present = false;
+        if (found.kind === 'hit') {
+            value = found.value;
+            present = true;
+        }
+        else if (port.default !== undefined) {
+            value = port.default;
+            present = true;
+        }
+        if (!present) {
+            if (port.required === true) {
+                missingRequired.push(port.name);
+            }
+            else {
+                missingOptional.push(port.name);
+            }
+            continue;
+        }
+        const coerced = coerceValue(port, value);
+        if (coerced.kind === 'error') {
+            typeErrors.push({ port: port.name, reason: coerced.reason });
+            continue;
+        }
+        inputs[port.name] = coerced.value;
+    }
+    if (missingRequired.length > 0 || ambiguous.length > 0 || typeErrors.length > 0) {
+        const lines = [];
+        if (missingRequired.length > 0) {
+            lines.push(`missing required input(s): ${missingRequired.join(', ')}`);
+        }
+        if (ambiguous.length > 0) {
+            for (const amb of ambiguous) {
+                lines.push(`input "${amb.port}" is produced by multiple upstreams ` +
+                    `(${amb.producers.join(', ')}) — disambiguate with "from: taskId.${amb.port}"`);
+            }
+        }
+        if (typeErrors.length > 0) {
+            for (const te of typeErrors) {
+                lines.push(`input "${te.port}": ${te.reason}`);
+            }
+        }
+        return {
+            kind: 'blocked',
+            missingRequired,
+            ambiguous,
+            typeErrors,
+            reason: lines.join('\n'),
+        };
+    }
+    return { kind: 'ready', inputs, missingOptional };
+}
+function findUpstreamValue(port, upstreamOutputs, dependsOn) {
+    // Explicit fully-qualified binding: "taskId.portName"
+    if (port.from && port.from.includes('.')) {
+        const dot = port.from.lastIndexOf('.');
+        const upstreamId = port.from.slice(0, dot);
+        const portName = port.from.slice(dot + 1);
+        const upstream = upstreamOutputs.get(upstreamId);
+        if (upstream && portName in upstream) {
+            return { kind: 'hit', producer: upstreamId, value: upstream[portName] };
+        }
+        return { kind: 'miss' };
+    }
+    // Name match (either explicit `from: "portName"` or defaulted to port.name)
+    const key = port.from ?? port.name;
+    const hits = [];
+    for (const upstreamId of dependsOn) {
+        const upstream = upstreamOutputs.get(upstreamId);
+        if (upstream && key in upstream) {
+            hits.push({ producer: upstreamId, value: upstream[key] });
+        }
+    }
+    if (hits.length === 0)
+        return { kind: 'miss' };
+    if (hits.length === 1)
+        return { kind: 'hit', producer: hits[0].producer, value: hits[0].value };
+    return { kind: 'ambiguous', producers: hits.map((h) => h.producer) };
+}
+function coerceValue(port, raw) {
+    switch (port.type) {
+        case 'string': {
+            if (typeof raw === 'string')
+                return { kind: 'ok', value: raw };
+            if (typeof raw === 'number' || typeof raw === 'boolean') {
+                return { kind: 'ok', value: String(raw) };
+            }
+            return { kind: 'error', reason: `expected string, got ${describe(raw)}` };
+        }
+        case 'number': {
+            if (typeof raw === 'number' && Number.isFinite(raw))
+                return { kind: 'ok', value: raw };
+            if (typeof raw === 'string' && raw.trim() !== '') {
+                const n = Number(raw);
+                if (Number.isFinite(n))
+                    return { kind: 'ok', value: n };
+            }
+            return { kind: 'error', reason: `expected number, got ${describe(raw)}` };
+        }
+        case 'boolean': {
+            if (typeof raw === 'boolean')
+                return { kind: 'ok', value: raw };
+            if (raw === 'true' || raw === 'false')
+                return { kind: 'ok', value: raw === 'true' };
+            return { kind: 'error', reason: `expected boolean, got ${describe(raw)}` };
+        }
+        case 'enum': {
+            const allowed = port.enum ?? [];
+            if (allowed.length === 0) {
+                return { kind: 'error', reason: 'enum port declared without "enum" values' };
+            }
+            const asStr = typeof raw === 'string' ? raw : String(raw);
+            if (!allowed.includes(asStr)) {
+                return {
+                    kind: 'error',
+                    reason: `value ${JSON.stringify(raw)} not in enum [${allowed.map((v) => JSON.stringify(v)).join(', ')}]`,
+                };
+            }
+            return { kind: 'ok', value: asStr };
+        }
+        case 'json':
+            // 'json' accepts anything that survives JSON round-trip. We don't
+            // validate deeply — users opt into `json` precisely because they
+            // want a free-form payload.
+            return { kind: 'ok', value: raw };
+        default: {
+            // Exhaustiveness — TypeScript won't let us reach here unless a
+            // new PortType is added without updating this switch. The return
+            // satisfies the type checker; in practice the default branch is
+            // dead code.
+            const _exhaustive = port.type;
+            void _exhaustive;
+            return { kind: 'error', reason: `unknown port type "${String(port.type)}"` };
+        }
+    }
+}
+function describe(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+/**
+ * Extract declared outputs from a terminated task's output streams.
+ *
+ * Strategy (v1 — intentionally dumb but predictable):
+ *   1. Prefer `normalizedOutput` when provided (AI drivers populate this
+ *      with the canonical assistant message; it's much cleaner than raw
+ *      stdout, which often has JSONL event dumps). Fall back to stdout
+ *      otherwise.
+ *   2. Scan from the end for the first non-empty line. If it parses as a
+ *      JSON object, use that as the source record.
+ *   3. If (2) fails, try parsing the entire source as JSON (supports
+ *      commands that pretty-print with line breaks).
+ *   4. For each declared output port, read the matching key and coerce
+ *      to the declared type. Coercion failures produce a diagnostic and
+ *      the port is absent from `outputs` (treated as missing downstream).
+ *
+ * When no declared outputs are present this returns an empty `outputs`
+ * map and null diagnostic — the engine interprets that as "task has no
+ * port contract".
+ */
+export function extractTaskOutputs(ports, stdout, normalizedOutput) {
+    const decl = ports?.outputs;
+    if (!decl || decl.length === 0) {
+        return { outputs: {}, diagnostic: null };
+    }
+    const source = (normalizedOutput ?? '').length > 0 ? normalizedOutput : stdout;
+    const record = parseJsonTail(source);
+    if (record === null) {
+        return {
+            outputs: {},
+            diagnostic: 'outputs: could not find a final-line JSON object in task output — declared outputs are unresolved',
+        };
+    }
+    const outputs = {};
+    const warnings = [];
+    for (const port of decl) {
+        if (!(port.name in record)) {
+            warnings.push(`missing key "${port.name}"`);
+            continue;
+        }
+        const coerced = coerceValue(port, record[port.name]);
+        if (coerced.kind === 'error') {
+            warnings.push(`"${port.name}": ${coerced.reason}`);
+            continue;
+        }
+        outputs[port.name] = coerced.value;
+    }
+    const diagnostic = warnings.length > 0 ? `outputs: ${warnings.join('; ')}` : null;
+    return { outputs, diagnostic };
+}
+/**
+ * Find the last non-empty line that parses as a JSON object. Returns
+ * null when no such line exists. Also tries the whole source as a
+ * fallback — covers pretty-printed JSON that spans multiple lines.
+ */
+function parseJsonTail(source) {
+    const lines = source.split(/\r?\n/);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        const parsed = safeParseJson(line);
+        if (parsed !== null)
+            return parsed;
+        // First non-empty line from the tail — if it didn't parse, fall through
+        // to the whole-source attempt below rather than scanning further up
+        // (otherwise a prior human-readable line would be silently picked up
+        // if it happened to contain `{...}` fragments).
+        break;
+    }
+    return safeParseJson(source.trim());
+}
+function safeParseJson(candidate) {
+    if (!candidate.startsWith('{'))
+        return null;
+    try {
+        const parsed = JSON.parse(candidate);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* not JSON */
+    }
+    return null;
+}
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

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

package/dist/prompt-doc.d.ts

@@ -1,4 +1,4 @@
-import type { PromptDocument, PromptContextBlock } from './types';
+import type { PortDef, PromptContextBlock, PromptDocument } from './types';
 /**
  * Build a fresh `PromptDocument` from a raw task string.
  * Middlewares receive this from the engine and push context blocks onto
@@ -33,4 +33,38 @@ export declare function serializePromptDocument(doc: PromptDocument): string;
  * appended to `contexts`, preserving immutability of `doc`.
  */
 export declare function appendContext(doc: PromptDocument, block: PromptContextBlock): PromptDocument;
+/**
+ * Helper: return a new document with the given block PREPENDED. The
+ * engine uses this to place port-related context blocks (`[Inputs]`,
+ * `[Output Format]`) at the top of the document so middlewares that
+ * assemble retrieval context against the task's inputs see them.
+ */
+export declare function prependContext(doc: PromptDocument, block: PromptContextBlock): PromptDocument;
+/**
+ * Build an `[Inputs]` context block from a map of resolved port inputs.
+ * Each input is rendered on its own line as `name: <value>` with an
+ * optional trailing `# <description>` comment so the model has both the
+ * value and the reason it matters.
+ *
+ * The block is *only* useful for AI tasks; command tasks consume inputs
+ * through `{{inputs.X}}` substitution in their command line and do not
+ * need this context.
+ *
+ * Returns null when there are no inputs to render — callers can forward
+ * that nullish value to `prependContext` via an `if (block)` check so
+ * empty-input tasks don't grow a noise block in their prompt.
+ */
+export declare function renderInputsBlock(inputsDecl: readonly PortDef[] | undefined, values: Readonly<Record<string, unknown>>): PromptContextBlock | null;
+/**
+ * Build an `[Output Format]` context block from a task's declared output
+ * ports. The block instructs the model to emit a final-line JSON object
+ * matching the declared schema so `extractTaskOutputs` can pick it up
+ * without fragile heuristics. Returns null when the task declares no
+ * outputs.
+ *
+ * The instruction is deliberately short and explicit — a terse "emit
+ * this object as JSON on the final line" beats a long schema dump
+ * because shorter prompts compose better with downstream middlewares.
+ */
+export declare function renderOutputSchemaBlock(outputsDecl: readonly PortDef[] | undefined): PromptContextBlock | null;
 //# sourceMappingURL=prompt-doc.d.ts.map

package/dist/prompt-doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-doc.d.ts","sourceRoot":"","sources":["../src/prompt-doc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAErE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAInE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,kBAAkB,GACxB,cAAc,CAEhB"}
+{"version":3,"file":"prompt-doc.d.ts","sourceRoot":"","sources":["../src/prompt-doc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE3E;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAErE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAInE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,kBAAkB,GACxB,cAAc,CAEhB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,kBAAkB,GACxB,cAAc,CAEhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,EAC1C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,kBAAkB,GAAG,IAAI,CAY3B;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,GAC1C,kBAAkB,GAAG,IAAI,CAsB3B"}

package/dist/prompt-doc.js

@@ -41,4 +41,114 @@ export function serializePromptDocument(doc) {
 export function appendContext(doc, block) {
     return { contexts: [...doc.contexts, block], task: doc.task };
 }
+/**
+ * Helper: return a new document with the given block PREPENDED. The
+ * engine uses this to place port-related context blocks (`[Inputs]`,
+ * `[Output Format]`) at the top of the document so middlewares that
+ * assemble retrieval context against the task's inputs see them.
+ */
+export function prependContext(doc, block) {
+    return { contexts: [block, ...doc.contexts], task: doc.task };
+}
+/**
+ * Build an `[Inputs]` context block from a map of resolved port inputs.
+ * Each input is rendered on its own line as `name: <value>` with an
+ * optional trailing `# <description>` comment so the model has both the
+ * value and the reason it matters.
+ *
+ * The block is *only* useful for AI tasks; command tasks consume inputs
+ * through `{{inputs.X}}` substitution in their command line and do not
+ * need this context.
+ *
+ * Returns null when there are no inputs to render — callers can forward
+ * that nullish value to `prependContext` via an `if (block)` check so
+ * empty-input tasks don't grow a noise block in their prompt.
+ */
+export function renderInputsBlock(inputsDecl, values) {
+    if (!inputsDecl || inputsDecl.length === 0)
+        return null;
+    const lines = [];
+    for (const port of inputsDecl) {
+        if (!(port.name in values))
+            continue;
+        const raw = values[port.name];
+        const rendered = renderInputValue(raw);
+        const descr = port.description?.trim();
+        lines.push(descr ? `${port.name}: ${rendered}  # ${descr}` : `${port.name}: ${rendered}`);
+    }
+    if (lines.length === 0)
+        return null;
+    return { label: 'Inputs', content: lines.join('\n') };
+}
+function renderInputValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Build an `[Output Format]` context block from a task's declared output
+ * ports. The block instructs the model to emit a final-line JSON object
+ * matching the declared schema so `extractTaskOutputs` can pick it up
+ * without fragile heuristics. Returns null when the task declares no
+ * outputs.
+ *
+ * The instruction is deliberately short and explicit — a terse "emit
+ * this object as JSON on the final line" beats a long schema dump
+ * because shorter prompts compose better with downstream middlewares.
+ */
+export function renderOutputSchemaBlock(outputsDecl) {
+    if (!outputsDecl || outputsDecl.length === 0)
+        return null;
+    const lines = [];
+    lines.push('After your response, emit a single JSON object on the FINAL line with these keys:');
+    for (const port of outputsDecl) {
+        const descr = port.description?.trim();
+        const enumHint = port.type === 'enum' && port.enum?.length
+            ? ` (one of: ${port.enum.map((v) => JSON.stringify(v)).join(', ')})`
+            : '';
+        lines.push(descr
+            ? `  - ${port.name} (${port.type}${enumHint}): ${descr}`
+            : `  - ${port.name} (${port.type}${enumHint})`);
+    }
+    const example = buildExampleObject(outputsDecl);
+    lines.push('');
+    lines.push(`Example final line: ${JSON.stringify(example)}`);
+    return { label: 'Output Format', content: lines.join('\n') };
+}
+function buildExampleObject(outputsDecl) {
+    const example = {};
+    for (const port of outputsDecl) {
+        if (port.default !== undefined) {
+            example[port.name] = port.default;
+            continue;
+        }
+        switch (port.type) {
+            case 'string':
+                example[port.name] = '...';
+                break;
+            case 'number':
+                example[port.name] = 0;
+                break;
+            case 'boolean':
+                example[port.name] = false;
+                break;
+            case 'enum':
+                example[port.name] = port.enum?.[0] ?? '...';
+                break;
+            case 'json':
+            default:
+                example[port.name] = null;
+        }
+    }
+    return example;
+}
 //# sourceMappingURL=prompt-doc.js.map

package/dist/prompt-doc.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-doc.js","sourceRoot":"","sources":["../src/prompt-doc.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAmB;IACzD,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC;IAC/C,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACrE,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAmB,EACnB,KAAyB;IAEzB,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;AAChE,CAAC"}
+{"version":3,"file":"prompt-doc.js","sourceRoot":"","sources":["../src/prompt-doc.ts"],"names":[],"mappings":"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"}

package/dist/runner.d.ts

@@ -2,6 +2,23 @@ import type { SpawnSpec, DriverPlugin, TaskResult } from './types';
 export interface RunOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
+    /**
+     * If set, stream the child's stdout to this file path as it arrives. The
+     * returned `TaskResult.stdout` is still a bounded in-memory tail
+     * (`maxStdoutTailBytes`) — callers that need the full output should read
+     * from the returned `stdoutPath`. Parent directories are created as needed.
+     */
+    readonly stdoutPath?: string;
+    /** Symmetric to `stdoutPath` for stderr. */
+    readonly stderrPath?: string;
+    /**
+     * Cap on bytes retained in memory for the returned `TaskResult.stdout`
+     * string. Defaults to `DEFAULT_STDOUT_TAIL_BYTES`. Bytes beyond this cap
+     * from the HEAD of the stream are dropped from the in-memory string; the
+     * on-disk file (if `stdoutPath` is set) is still the full output.
+     */
+    readonly maxStdoutTailBytes?: number;
+    readonly maxStderrTailBytes?: number;
 }
 /**
  * R2: Validate a SpawnSpec returned by a third-party driver. Returns null on

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAiCnE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAoJD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoClF;AAED,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,UAAU,CAAC,CAiNrB;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,UAAU,CAAC,CAMrB"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AA4CnE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AA4RD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoClF;AAED,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,UAAU,CAAC,CA0OrB;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,UAAU,CAAC,CAMrB"}