@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/workflows/subprocess-entry.d.ts

@@ -0,0 +1,38 @@
+/** The argv marker that selects the worker role. */
+export declare const WORKFLOW_WORKER_ARGV_FLAG = "__workflow-worker";
+/**
+ * The DISCRIMINATOR. `__workflow-worker` alone means "the worker role was selected"; this flag means
+ * "and a real parent is on the other end of stdio, driving the NDJSON bridge."
+ *
+ * The split exists because R5-15's contract test (frozen) invokes `workflowWorkerMain` with
+ * `["winter", "__workflow-worker", "--run-id", "wf_1"]` and requires the not-implemented exit code
+ * back PROMPTLY. A worker that treated the role flag alone as "start reading init from stdin" would
+ * block that test forever on a stream nothing will ever write to. It also keeps `verify:workflow`'s
+ * RED/GREEN meaningful: a bare role invocation answers 78 in every build, while a bridged one
+ * answers 78 only while the body is a stub.
+ */
+export declare const WORKFLOW_WORKER_BRIDGE_FLAG = "--bridge";
+/**
+ * Returned when the worker role was selected but no parent is driving it (no
+ * `--bridge` flag on argv). Distinct from a plain `1` so `verify:workflow` can report "the dispatch
+ * works, the worker is not being driven" rather than an indistinguishable generic failure.
+ *
+ * PRESERVED NAME AND VALUE (the spine's contract test asserts both, and asserts this exact code for
+ * a bare `__workflow-worker` argv). Its MEANING widened when the body landed: before, every
+ * invocation returned it; now only an undriven one does. That is precisely what makes
+ * `verify:workflow` a real RED/GREEN gate -- it drives the worker WITH the bridge flag, so it saw 78
+ * against the stub and sees a real run against this body.
+ */
+export declare const WORKFLOW_WORKER_NOT_IMPLEMENTED_EXIT_CODE = 78;
+/**
+ * The worker itself broke -- an unreadable init line, an I/O failure. NOT the code for "the workflow
+ * failed": a failed workflow reports through the terminal `error` bridge op and still exits 0,
+ * because the parent already knows what happened and a non-zero code there would make a script bug
+ * indistinguishable from a runtime bug (R5-15's own stated reason for returning a code at all).
+ */
+export declare const WORKFLOW_WORKER_BROKEN_EXIT_CODE = 70;
+export declare function workflowWorkerMain(argv: string[], io: {
+    stdin: NodeJS.ReadableStream;
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+}): Promise<number>;

package/dist/workflows/subprocess-entry.js

@@ -0,0 +1,14 @@
+import {
+  WORKFLOW_WORKER_ARGV_FLAG2,
+  WORKFLOW_WORKER_BRIDGE_FLAG2,
+  WORKFLOW_WORKER_NOT_IMPLEMENTED_EXIT_CODE2,
+  WORKFLOW_WORKER_BROKEN_EXIT_CODE2,
+  workflowWorkerMain2
+} from "../index-bef62z3r.js";
+export {
+  WORKFLOW_WORKER_ARGV_FLAG2 as WORKFLOW_WORKER_ARGV_FLAG,
+  WORKFLOW_WORKER_BRIDGE_FLAG2 as WORKFLOW_WORKER_BRIDGE_FLAG,
+  WORKFLOW_WORKER_BROKEN_EXIT_CODE2 as WORKFLOW_WORKER_BROKEN_EXIT_CODE,
+  WORKFLOW_WORKER_NOT_IMPLEMENTED_EXIT_CODE2 as WORKFLOW_WORKER_NOT_IMPLEMENTED_EXIT_CODE,
+  workflowWorkerMain2 as workflowWorkerMain
+};

package/dist/workflows/transcript.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Per-field byte cap. The full values live elsewhere -- an agent's result in the journal and in the
+ * child's own transcript, the run's result in the task output file -- so this file bounds what a
+ * long-running workflow can write into the durable projects area. 2 KB keeps a prompt and a result
+ * legible at a glance, which is what a diagnostic surface is for.
+ */
+export declare const TRANSCRIPT_FIELD_MAX_BYTES = 2048;
+/** UTF-8 byte cap on a byte boundary -- `skills/frontmatter.ts`'s `capBytes`, same rule, same reason. */
+declare function capField(value: string): string;
+/** A string passes through; anything else is JSON. Then capped. Mirrors `renderResult`'s rule so the two surfaces agree. */
+declare function renderCapped(value: unknown): string;
+export type WorkflowTranscriptEntry = {
+    kind: "launch";
+    runId: string;
+    name: string;
+    scriptPath: string;
+    args?: string;
+    resumedFrom?: string;
+    replayed?: number;
+} | {
+    kind: "agent";
+    prompt: string;
+    outcome: "value" | "null" | "refused";
+    value?: string;
+    phase?: string;
+    label?: string;
+} | {
+    kind: "phase";
+    title: string;
+    declared: boolean;
+} | {
+    kind: "finish";
+    status: "completed" | "failed" | "stopped";
+    detail?: string;
+};
+/**
+ * One run's transcript: append-only NDJSON at `<transcriptDir>/transcript.jsonl`.
+ *
+ * The directory is created by the caller (`runtime.ts` creates and reports it in the same breath),
+ * so this class only appends -- and swallows every error, per this module's header.
+ */
+export declare class RunTranscript {
+    private readonly path;
+    constructor(transcriptDir: string);
+    append(entry: WorkflowTranscriptEntry): void;
+    /** The `agent()` record, with the value rendered and capped here so callers never do it twice. */
+    agent(input: {
+        prompt: string;
+        value: unknown;
+        resolvedNull: boolean;
+        phase?: string;
+        label?: string;
+    }): void;
+    finish(status: "completed" | "failed" | "stopped", detail?: string): void;
+}
+export { capField as capTranscriptField, renderCapped as renderTranscriptValue };

package/dist/workflows/types.d.ts

@@ -0,0 +1,84 @@
+/** WS-11 §1.8: `running -> completed | failed | stopped`, a ONE-WAY lifecycle. */
+export type WorkflowStatus = "running" | "completed" | "failed" | "stopped";
+export interface WorkflowCounts {
+    running: number;
+    completed: number;
+    total: number;
+}
+/**
+ * WS-11 §1.6's `agent()` options table, in full. Norma's original carried `{label, model, schema}`;
+ * `phase`, `effort`, `isolation` and `agentType` are the CC-contract widening.
+ *
+ * SERIALIZED ACROSS THE BRIDGE and used verbatim inside `promptKey`, so every field must be plain
+ * JSON data -- a function or class instance here would break both the wire and the resume cache.
+ */
+export interface AgentOpts {
+    /** Display-label override for the progress tree. */
+    label?: string;
+    /** Explicit progress-group assignment -- avoids racing the global `phase()` state inside `pipeline`/`parallel` stages. */
+    phase?: string;
+    /** JSON Schema. Forces the child onto the StructuredOutput mechanism (WS-11 §8) via `SpawnChildRequest.outputFormat`. */
+    schema?: unknown;
+    /** Per-child model override; omitted -> the child inherits the resolved session model (WS-10). */
+    model?: string;
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    /** WS-10 §8: a fresh git worktree per agent, auto-removed when unchanged. */
+    isolation?: "worktree";
+    /** A custom subagent type resolved from the same registry the Agent tool uses; composes with `schema`. */
+    agentType?: string;
+}
+/** A read-only projection of a run -- plain-cloneable, no AbortController, safe to hand to a caller. */
+export interface WorkflowRunView {
+    runId: string;
+    sessionId: string;
+    taskId: string;
+    name: string;
+    status: WorkflowStatus;
+    counts: WorkflowCounts;
+    phase?: string;
+    result?: string;
+    error?: string;
+    startedAt: number;
+}
+/**
+ * `WorkflowInput`, `sdk-tools.d.ts:2758-2789`. Seven fields, ALL optional at the declaration; the
+ * "at least one of `script`/`name`/`scriptPath`" rule is a runtime validation, not a type one,
+ * exactly as the pin has it.
+ */
+export interface WorkflowInput {
+    script?: string;
+    name?: string;
+    /** Accepted and IGNORED -- the meta block owns metadata (`sdk-tools.d.ts:2768`). */
+    description?: string;
+    /** Accepted and IGNORED (`sdk-tools.d.ts:2772`). */
+    title?: string;
+    args?: {
+        [k: string]: unknown;
+    };
+    /** Takes PRECEDENCE over `script` and `name` (`sdk-tools.d.ts:2782`). */
+    scriptPath?: string;
+    /** Same-session only, and only after the prior run has stopped (`sdk-tools.d.ts:2786`). */
+    resumeFromRunId?: string;
+}
+/**
+ * `WorkflowOutput`, `sdk-tools.d.ts:4053-4089` -- declared in full, so this is a MIRROR, not a
+ * Winter invention. `status` and `taskId` are the only required fields.
+ *
+ * Winter implements the LOCAL half only: `remote_launched`/`sessionUrl` are declared here for
+ * fidelity to the pinned union but are never produced (`WorkflowInput` declares no `remote` field --
+ * item (g)'s own asymmetry note).
+ */
+export interface WorkflowOutput {
+    status: "async_launched" | "remote_launched";
+    taskId: string;
+    taskType?: "local_workflow" | "remote_agent";
+    workflowName?: string;
+    runId?: string;
+    summary?: string;
+    transcriptDir?: string;
+    scriptPath?: string;
+    sessionUrl?: string;
+    warning?: string;
+    /** Doc-asserted (`4086`) to be set when the SYNTAX CHECK fails -- a script that fails validation still returns a WorkflowOutput. */
+    error?: string;
+}

package/dist/workflows/worker-harness.d.ts

@@ -0,0 +1,45 @@
+import { type BridgeRequest, type WorkflowRef } from "./bridge.js";
+import type { JournalEntry } from "./journal.js";
+import type { BudgetSnapshot } from "./budget.js";
+import type { WorkerSpawner } from "./runtime.js";
+export interface InProcessWorkerOptions {
+    source?: string;
+    args?: unknown;
+    argv?: string[];
+    concurrency?: number;
+    totalAgentCap?: number;
+    maxItemsPerCall?: number;
+    budget?: BudgetSnapshot;
+    resumeJournal?: JournalEntry[];
+    /** Skip writing an init line at all -- for the undriven-argv cases. */
+    skipInit?: boolean;
+    /** Write this instead of a well-formed init line (the malformed-init case). */
+    rawInit?: string;
+    answerAgent?: (req: {
+        prompt: string;
+        opts?: unknown;
+        callId: number;
+    }) => Promise<{
+        value?: unknown;
+        error?: string;
+        budget?: BudgetSnapshot;
+        delayMs?: number;
+    }>;
+    answerWorkflow?: (ref: WorkflowRef, args: unknown) => Promise<{
+        ok: true;
+        source: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}
+export interface InProcessWorkerResult {
+    exitCode: number;
+    requests: BridgeRequest[];
+    /** The `done` or `error` frame, when one was produced. */
+    terminal: BridgeRequest | undefined;
+    stdoutLines: string[];
+    stderr: string;
+}
+export declare function runWorkerInProcess(opts: InProcessWorkerOptions): Promise<InProcessWorkerResult>;
+export declare function inProcessWorkerSpawner(): WorkerSpawner;

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@yanlinglabs/winter-agent-runtime",
+  "version": "0.0.27",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yanlingLabs/winter-agent-sdk.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/yanlingLabs/winter-agent-sdk",
+  "bugs": {
+    "url": "https://github.com/yanlingLabs/winter-agent-sdk/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./embedded": {
+      "types": "./dist/embedded.d.ts",
+      "default": "./dist/embedded.js"
+    },
+    "./embedded-host": {
+      "types": "./dist/embedded-host.d.ts",
+      "default": "./dist/embedded-host.js"
+    },
+    "./embedded-worker": {
+      "types": "./dist/embedded-worker.d.ts",
+      "default": "./dist/embedded-worker.js"
+    },
+    "./workflow-worker": {
+      "types": "./dist/workflows/subprocess-entry.d.ts",
+      "default": "./dist/workflows/subprocess-entry.js"
+    },
+    "./version": {
+      "types": "./dist/version.d.ts",
+      "default": "./dist/version.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "winter": {
+    "publish": {
+      "npm": true
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.1.0",
+    "ajv": "^8.20.0",
+    "ignore": "7.0.5",
+    "@yanlinglabs/winter-provider-runtime": "0.0.27",
+    "@yanlinglabs/winter-agent-sdk": "0.0.27",
+    "@yanlinglabs/winter-provider-catalog": "0.0.27"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/server": "^2.1.0"
+  },
+  "scripts": {}
+}