@tagma/sdk 0.7.3 → 0.7.5

package/dist/ports.d.ts

@@ -1,196 +0,0 @@
-import type { PortDef, PortType, TaskConfig, TaskOutputBindings, TaskPorts } from './types';
-/**
- * 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 declare function extractInputReferences(text: string): string[];
-export interface SubstituteResult {
-    readonly text: string;
-    /** Port names that appeared in placeholders but weren't in `inputs`. */
-    readonly unresolved: readonly string[];
-}
-/**
- * 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 declare function substituteInputs(text: string, inputs: Readonly<Record<string, unknown>>): SubstituteResult;
-export type InputResolution = {
-    readonly kind: 'ready';
-    readonly inputs: Readonly<Record<string, unknown>>;
-    /**
-     * Optional inputs that had no upstream producer and no default;
-     * they are absent from `inputs` (so placeholders render empty).
-     * Separate from `missingRequired` so the engine can log softly
-     * without blocking the task.
-     */
-    readonly missingOptional: readonly string[];
-} | {
-    readonly kind: 'blocked';
-    /** Required port names that could not be satisfied. */
-    readonly missingRequired: readonly string[];
-    /** Port names with multiple ambiguous producers. */
-    readonly ambiguous: readonly {
-        port: string;
-        producers: readonly string[];
-    }[];
-    /** Port names whose resolved value failed type coercion. */
-    readonly typeErrors: readonly {
-        port: string;
-        reason: string;
-    }[];
-    /** Human-readable multi-line description for the engine to log. */
-    readonly reason: string;
-};
-/**
- * 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 declare function resolveTaskInputs(task: TaskConfig, upstreamOutputs: ReadonlyMap<string, Readonly<Record<string, unknown>>>, dependsOn: readonly string[]): InputResolution;
-export interface UpstreamBindingData {
-    readonly outputs?: Readonly<Record<string, unknown>> | null;
-    readonly stdout?: string;
-    readonly stderr?: string;
-    readonly normalizedOutput?: string | null;
-    readonly exitCode?: number | null;
-}
-export type BindingInputResolution = {
-    readonly kind: 'ready';
-    readonly inputs: Readonly<Record<string, unknown>>;
-    readonly missingOptional: readonly string[];
-} | {
-    readonly kind: 'blocked';
-    readonly missingRequired: readonly string[];
-    readonly ambiguous: readonly {
-        input: string;
-        producers: readonly string[];
-    }[];
-    readonly typeErrors: readonly {
-        input: string;
-        reason: string;
-    }[];
-    readonly reason: string;
-};
-export declare function resolveTaskBindingInputs(task: Pick<TaskConfig, 'inputs'>, upstreamData: ReadonlyMap<string, UpstreamBindingData>, dependsOn: readonly string[]): BindingInputResolution;
-export interface ExtractResult {
-    /** Coerced values keyed by port name. Ports that failed to resolve are absent. */
-    readonly outputs: Readonly<Record<string, unknown>>;
-    /**
-     * Human-readable diagnostic describing what went wrong, if anything.
-     * `null` when every declared output was resolved cleanly. The engine
-     * appends this to stderr so the pipeline log explains why downstream
-     * inputs are missing.
-     */
-    readonly diagnostic: string | null;
-}
-/**
- * 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 declare function extractTaskOutputs(ports: TaskPorts | undefined, stdout: string, normalizedOutput: string | null): ExtractResult;
-export declare function extractTaskBindingOutputs(bindings: TaskOutputBindings | undefined, stdout: string, stderr: string, normalizedOutput: string | null): ExtractResult;
-export interface PromptUpstreamNeighbor {
-    readonly taskId: string;
-    /**
-     * Declared outputs of the upstream task. `undefined` signals that the
-     * neighbor is a Prompt Task (no structured contribution) or otherwise
-     * has no outputs to offer. The inference logic treats `undefined` and
-     * an empty array the same way — neither contributes ports.
-     */
-    readonly outputs: readonly PortDef[] | undefined;
-}
-export interface PromptDownstreamNeighbor {
-    readonly taskId: string;
-    /**
-     * Declared inputs of the downstream task. `undefined` signals a
-     * Prompt-Task neighbor or a Command Task without declared inputs.
-     * Either way it contributes no ports to the inferred output contract.
-     */
-    readonly inputs: readonly PortDef[] | undefined;
-}
-export interface PromptPortConflict {
-    readonly portName: string;
-    readonly producers: readonly {
-        readonly taskId: string;
-        readonly type: PortType;
-    }[];
-    /** Pre-formatted human-readable reason for logs / stderr. */
-    readonly reason: string;
-}
-export interface PromptPortInference {
-    /**
-     * Synthetic `TaskPorts` the engine feeds into the resolve / substitute /
-     * render / extract helpers, exactly as if the Prompt had declared these
-     * ports itself. Empty arrays are preserved as absent so downstream code
-     * paths treat "no ports" uniformly (see engine.ts's existing
-     * `task.ports?.outputs && task.ports.outputs.length > 0` guard).
-     */
-    readonly ports: TaskPorts;
-    readonly inputConflicts: readonly PromptPortConflict[];
-    readonly outputConflicts: readonly PromptPortConflict[];
-}
-/**
- * Derive the effective `TaskPorts` for a Prompt Task from its direct
- * neighbors. See the module-level "Prompt-task port inference" comment
- * for the full contract.
- *
- * Pure function — no side effects, safe to call from the CLI, editor
- * preview, and engine hot path alike.
- */
-export declare function inferPromptPorts(input: {
-    readonly upstreams: readonly PromptUpstreamNeighbor[];
-    readonly downstreams: readonly PromptDownstreamNeighbor[];
-}): PromptPortInference;
-//# sourceMappingURL=ports.d.ts.map

package/dist/ports.d.ts.map

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