@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/context/winter-md.d.ts

@@ -0,0 +1,81 @@
+import { type BrandProfile, type SettingSource } from "@yanlinglabs/winter-agent-sdk";
+/**
+ * Winter's OWN instructions basename, derived from the default profile rather than spelled.
+ *
+ * Kept as a named export because it is what every caller that has not threaded a brand still means.
+ * A session's actual basename is `input.brand.instructionsFile` inside `discoverWinterMd` below.
+ */
+export declare const WINTER_MD_BASENAME: string;
+/**
+ * WS-21 §6.3 item 10 (F7): there is NO per-file byte ceiling here any more. Winter used to cap an
+ * instructions file at 32 KB (Norma's shipped cap); claude does not truncate `CLAUDE.md`, and the
+ * whole point of this workstream is that the two runtimes read the identical file the identical way.
+ * Removed rather than widened, so nothing downstream can quietly reintroduce a cap by reading this
+ * constant.
+ */
+export interface WinterMdBlock {
+    /** Absolute path of the file this block came from. */
+    path: string;
+    /** `local` is the per-directory `<name>.local.md` (claude's `CLAUDE.local.md`), gated on the `local` source. */
+    scope: "user" | "project" | "local";
+    /**
+     * SDK 0.0.16: the file's CONTENT (capped, a literal `<system-reminder>` tag neutralised) --
+     * unwrapped, since it now renders as one entry of the index-0 userContext's `claudeMd` value
+     * (`renderInstructionsContext`) rather than as its own reminder block.
+     */
+    text: string;
+}
+/** `<name>.md` -> `<name>.local.md`: claude's `CLAUDE.local.md` convention with the session's own basename. */
+export declare function localInstructionsBasename(instructionsFile: string): string;
+/** TEST-ONLY: throwaway repositories at reused paths need this cleared. Production never calls it. */
+export declare function _clearProjectRootCacheForTests(): void;
+/**
+ * The root of the checkout `cwd` lives in -- `git rev-parse --show-toplevel`, which for a LINKED
+ * WORKTREE is that worktree's own directory (not the main checkout, and not the common dir).
+ * `null` when `cwd` is not inside a repository, or git is unavailable: with no repository there is
+ * no defensible upper bound for a parent-walk, so the caller reads the cwd alone rather than
+ * climbing toward `/`.
+ */
+export declare function projectInstructionRoot(cwd: string): string | null;
+export interface WinterMdInput {
+    cwd: string;
+    /** The `~/.winter` root. */
+    home: string;
+    /** Omitted means the pinned default: all three tiers. `[]` reads nothing. */
+    settingSources?: readonly SettingSource[];
+    /** P7a (D19): the session's brand. Omitted = `WINTER_BRAND`, i.e. today's `WINTER_MD_BASENAME`. */
+    brand?: Pick<BrandProfile, "instructionsFile">;
+    /**
+     * WS-21 §6.3 item 2: UNCONDITIONAL rules (`context/rules.ts`'s `loadRules(...).unconditional`),
+     * rendered as additional blocks AFTER every instructions file -- rules are standing context of
+     * the identical kind an instructions file is, just organised one file per rule instead of a
+     * single instructions basename. A CONDITIONAL rule never belongs here: it rides the on-touch attachment
+     * (`conditionalRuleAttachmentProducer`) instead, appearing only once a matching file is touched.
+     */
+    rules?: readonly {
+        path: string;
+        tier: "user" | "project";
+        content: string;
+    }[];
+}
+/**
+ * The instructions blocks for a session, in the PINNED ORDER: the user-level file first, then every
+ * project file from the repository root down to the cwd, then every unconditional rule.
+ *
+ * User-first is deliberate. The user's own file under the winter home is standing preference; a
+ * project's file is specific to the work in front of the model. Reading the specific thing last
+ * matches the outermost-first rule the project walk already follows, so one rule covers the whole
+ * ordering rather than two that could drift. Rules come last because they are the most granular
+ * tier -- narrower in scope than either instructions file, the same reason a project file already
+ * reads after the user's.
+ */
+export declare function discoverWinterMd(input: WinterMdInput): WinterMdBlock[];
+export declare const INSTRUCTIONS_CONTEXT_HEADER = "Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.";
+export type InstructionsContextKind = WinterMdBlock["scope"] | "auto-memory";
+export interface InstructionsContextFile {
+    path: string;
+    kind: InstructionsContextKind;
+    content: string;
+}
+/** The `claudeMd` userContext value, or `undefined` when no file has content (the key is then omitted). */
+export declare function renderInstructionsContext(files: readonly InstructionsContextFile[]): string | undefined;

package/dist/embedded-host.d.ts

@@ -0,0 +1,48 @@
+import type { SpawnedRuntimeProcess, SpawnRuntimeOptions } from "@yanlinglabs/winter-agent-sdk";
+import type { EmbeddedWorkflowWorkerCommand } from "./embedded-protocol.js";
+export type { EmbeddedHostMessage, EmbeddedWorkerMessage, EmbeddedWorkflowWorkerCommand } from "./embedded-protocol.js";
+/**
+ * How long `kill()` lets an aborted session unwind before `terminate()`.
+ *
+ * The abort itself is fast -- process groups die synchronously, the turn is interrupted, the engine's
+ * teardown is milliseconds -- so this is a BACKSTOP for a Worker that cannot answer (stuck in
+ * synchronous code, or a turn the interrupt could not reach). Long enough that an ordinary abort always
+ * finishes inside it: a graceful end closes the transcript lease and MCP clients, which `terminate()`
+ * cannot. A host with its own shutdown budget calls `terminate()` itself when that budget runs out.
+ */
+export declare const EMBEDDED_KILL_GRACE_MS = 1500;
+export interface SpawnEmbeddedWorkerOptions {
+    /**
+     * The Worker entry as THIS host must spell it. In a `bun build --compile` binary that is the plain
+     * relative path of the host's own worker file as it was passed to `--compile` (`"./embedded-worker.ts"`
+     * beside the main entry) -- a `new URL(…, import.meta.url).href` hangs there. In dev, an absolute path.
+     */
+    workerEntry: string;
+    /** What `query()` handed the spawn hook: `args` (the argv), `env` (the session's whole environment). */
+    spawn: SpawnRuntimeOptions;
+    /** The workflow worker's spawn command, forwarded to the session (see `workflows/sandbox.ts`). */
+    workflowWorkerCommand?: EmbeddedWorkflowWorkerCommand;
+    /** Default `EMBEDDED_KILL_GRACE_MS`. */
+    killGraceMs?: number;
+    /** Test seam over the Worker constructor. The default is `new Worker(entry, { env })`. */
+    createWorker?: (entry: string, env: Record<string, string>) => Worker;
+    /**
+     * Hold the `start` message until this settles (either way). The Worker is constructed at once and
+     * buffers stdin meanwhile, but NO engine runs until then. For a host that must not overlap two
+     * incarnations of one session on one transcript: every Worker shares the host's pid, so the
+     * transcript lease cannot keep them apart -- the host passes the previous incarnation's `exited`.
+     */
+    startAfter?: Promise<unknown>;
+}
+export interface EmbeddedWorkerProcess extends SpawnedRuntimeProcess {
+    /** Hard stop NOW -- the backstop `kill()` arms, exposed for a host whose own budget ran out. Idempotent. */
+    terminate(): void;
+    /** `running` → (`kill()`) `stopping` → `closed`. `closed` means `exited` has settled. */
+    readonly state: "running" | "stopping" | "closed";
+}
+/**
+ * Construct the Worker, send `start`, and return the process handle. Never throws for a Worker that
+ * fails to LOAD (an unresolvable entry is an `error` event + `close`, measured) -- that surfaces as an
+ * exit with code 1 and the reason on `stderr`, which the wrapper maps to "exited before init".
+ */
+export declare function spawnEmbeddedWorker(opts: SpawnEmbeddedWorkerOptions): EmbeddedWorkerProcess;

package/dist/embedded-host.js

@@ -0,0 +1,155 @@
+import {
+  Queue
+} from "./index-97t2rmtf.js";
+
+// src/embedded-host.ts
+var EMBEDDED_KILL_GRACE_MS = 1500;
+var CLOSE_AFTER_EXIT_MS = 2000;
+function describeError(event) {
+  const e = event;
+  if (e?.error instanceof Error && e.error.message !== "")
+    return e.error.message;
+  if (typeof e?.message === "string" && e.message !== "") {
+    const lines = e.message.split(`
+`).map((l) => l.trim()).filter((l) => l !== "");
+    const errorLine = lines.find((l) => /^(\w*Error|error):/.test(l));
+    return (errorLine ?? lines[0] ?? e.message).slice(0, 500);
+  }
+  return "unknown worker error";
+}
+function spawnEmbeddedWorker(opts) {
+  const stdout = new Queue;
+  const stderr = new Queue;
+  const graceMs = opts.killGraceMs ?? EMBEDDED_KILL_GRACE_MS;
+  let state = "running";
+  let exitCode;
+  let crashed = false;
+  let terminatedByHost = false;
+  let stdinEnded = false;
+  let graceTimer;
+  let closeTimer;
+  let settleExited;
+  const exited = new Promise((resolve) => {
+    settleExited = resolve;
+  });
+  const worker = (opts.createWorker ?? ((entry, env) => new Worker(entry, { env })))(opts.workerEntry, opts.spawn.env);
+  const send = (message) => {
+    if (state === "closed")
+      return;
+    try {
+      worker.postMessage(message);
+    } catch {}
+  };
+  const onClosed = () => {
+    if (state === "closed")
+      return;
+    state = "closed";
+    if (graceTimer !== undefined)
+      clearTimeout(graceTimer);
+    if (closeTimer !== undefined)
+      clearTimeout(closeTimer);
+    stdout.end();
+    stderr.end();
+    if (crashed)
+      settleExited({ code: 1, signal: null });
+    else if (exitCode !== undefined)
+      settleExited({ code: exitCode, signal: null });
+    else if (terminatedByHost)
+      settleExited({ code: null, signal: "SIGKILL" });
+    else
+      settleExited({ code: 1, signal: null });
+  };
+  const terminate = () => {
+    if (state === "closed")
+      return;
+    if (exitCode === undefined)
+      terminatedByHost = true;
+    try {
+      worker.terminate();
+    } catch {}
+  };
+  worker.onmessage = (event) => {
+    const message = event.data;
+    switch (message.kind) {
+      case "stdout":
+        stdout.write(message.chunk);
+        return;
+      case "stderr":
+        stderr.write(message.chunk);
+        return;
+      case "exit":
+        exitCode = message.code;
+        closeTimer = setTimeout(terminate, CLOSE_AFTER_EXIT_MS);
+        closeTimer.unref?.();
+        return;
+    }
+  };
+  worker.onerror = (event) => {
+    crashed = exitCode === undefined;
+    try {
+      event.preventDefault?.();
+    } catch {}
+    stderr.write(`winter: embedded runtime worker failed: ${describeError(event)}
+`);
+    terminate();
+  };
+  worker.addEventListener("messageerror", () => {
+    crashed = exitCode === undefined;
+    stderr.write(`winter: embedded runtime worker sent a message the host could not decode
+`);
+    terminate();
+  });
+  worker.addEventListener("close", onClosed);
+  const start = { kind: "start", argv: [...opts.spawn.args], ...opts.workflowWorkerCommand !== undefined ? { workflowWorkerCommand: opts.workflowWorkerCommand } : {} };
+  if (opts.startAfter === undefined)
+    send(start);
+  else
+    opts.startAfter.then(() => send(start), () => send(start));
+  const kill = (_signal) => {
+    if (state !== "running") {
+      return;
+    }
+    state = "stopping";
+    send({ kind: "abort" });
+    if (!stdinEnded) {
+      stdinEnded = true;
+      send({ kind: "stdin-end" });
+    }
+    graceTimer = setTimeout(terminate, graceMs);
+    graceTimer.unref?.();
+  };
+  if (opts.spawn.signal !== undefined) {
+    if (opts.spawn.signal.aborted)
+      kill();
+    else
+      opts.spawn.signal.addEventListener("abort", () => kill(), { once: true });
+  }
+  return {
+    stdin: {
+      write(chunk) {
+        if (stdinEnded)
+          return;
+        send({ kind: "stdin", chunk });
+      },
+      end() {
+        if (stdinEnded)
+          return;
+        stdinEnded = true;
+        send({ kind: "stdin-end" });
+      }
+    },
+    stdout,
+    stderr,
+    kill,
+    terminate,
+    exited,
+    pid: null,
+    get state() {
+      return state;
+    }
+  };
+}
+export {
+  EMBEDDED_KILL_GRACE_MS,
+  spawnEmbeddedWorker
+};

package/dist/embedded-protocol.d.ts

@@ -0,0 +1,44 @@
+/** A worker-side spawn command (the workflow worker's `(file, args)`), structurally `workflows/sandbox.ts`'s `WorkerCommand`. */
+export interface EmbeddedWorkflowWorkerCommand {
+    file: string;
+    args: string[];
+}
+/** Host → Worker. `start` is sent exactly once, first; everything else may follow in any order. */
+export type EmbeddedHostMessage = {
+    kind: "start";
+    /** The same argv a spawned child gets (`--run --config-json <json>`); found by flag NAME, never by position. */
+    argv: string[];
+    /**
+     * The workflow worker's spawn command as the HOST must spell it. Absent = the runtime's own
+     * default (`process.execPath __workflow-worker --bridge`), which is WRONG inside a host binary
+     * whose main routes `__workflow-worker` somewhere else -- see `workflows/sandbox.ts`.
+     */
+    workflowWorkerCommand?: EmbeddedWorkflowWorkerCommand;
+} | {
+    kind: "stdin";
+    chunk: string;
+} | {
+    kind: "stdin-end";
+}
+/** The embedded SIGTERM: kill background process groups, end the turn, let the engine return. */
+ | {
+    kind: "abort";
+};
+/** Worker → Host. `exit` is the last message a healthy Worker posts; the Worker closes right after it. */
+export type EmbeddedWorkerMessage = {
+    kind: "stdout";
+    chunk: string;
+} | {
+    kind: "stderr";
+    chunk: string;
+} | {
+    kind: "exit";
+    code: number;
+};
+/**
+ * The request ids of the two control frames an ABORT synthesizes (`embedded.ts`). Fixed strings, not
+ * UUIDs, so the output filter can recognise their acknowledgements without state: no host ever
+ * mints a request id in this namespace (the wrapper uses `randomUUID()`).
+ */
+export declare const EMBEDDED_ABORT_END_INPUT_REQUEST_ID = "embedded-abort:end_input";
+export declare const EMBEDDED_ABORT_INTERRUPT_REQUEST_ID = "embedded-abort:interrupt";

package/dist/embedded-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/embedded-worker.js

@@ -0,0 +1,74 @@
+import"./index-9qgkpv56.js";
+import"./index-bef62z3r.js";
+import"./index-584yahed.js";
+import {
+  runEmbeddedSession2
+} from "./index-rkhh0457.js";
+import {
+  Queue
+} from "./index-97t2rmtf.js";
+
+// src/embedded-worker.ts
+import { isMainThread } from "node:worker_threads";
+function post(message) {
+  postMessage(message);
+}
+function fenceProcessWideState() {
+  const readUmask = process.umask.bind(process);
+  process.chdir = (directory) => {
+    throw new Error(`process.chdir(${JSON.stringify(directory)}) is refused inside an embedded Winter session: the working directory is process-wide and the host daemon's; pass the session cwd explicitly instead`);
+  };
+  process.umask = (mask) => {
+    if (mask !== undefined)
+      throw new Error("process.umask(mask) is refused inside an embedded Winter session: the file-mode mask is process-wide and the host daemon's");
+    return readUmask();
+  };
+}
+function installEmbeddedWorker() {
+  fenceProcessWideState();
+  const input = new Queue;
+  const abort = new AbortController;
+  let started = false;
+  const run = async (start) => {
+    let code = 1;
+    try {
+      code = await runEmbeddedSession2({
+        argv: start.argv,
+        env: process.env,
+        input,
+        write: (chunk) => post({ kind: "stdout", chunk }),
+        writeErr: (chunk) => post({ kind: "stderr", chunk }),
+        signal: abort.signal,
+        ...start.workflowWorkerCommand !== undefined ? { workflowWorkerCommand: start.workflowWorkerCommand } : {}
+      });
+    } catch (err) {
+      post({ kind: "stderr", chunk: `winter: fatal (embedded worker): ${err instanceof Error ? err.stack ?? err.message : String(err)}
+` });
+      code = 1;
+    }
+    post({ kind: "exit", code });
+    process.exit(code);
+  };
+  self.onmessage = (event) => {
+    const message = event.data;
+    switch (message.kind) {
+      case "start":
+        if (started)
+          return;
+        started = true;
+        run(message);
+        return;
+      case "stdin":
+        input.write(message.chunk);
+        return;
+      case "stdin-end":
+        input.end();
+        return;
+      case "abort":
+        abort.abort();
+        return;
+    }
+  };
+}
+if (!isMainThread)
+  installEmbeddedWorker();

package/dist/embedded.d.ts

@@ -0,0 +1,34 @@
+import { type WorkerCommand } from "./workflows/sandbox.js";
+export interface EmbeddedSessionOptions {
+    /** The spawn argv (`--run --config-json <json>`, any leading slots); flags are found by NAME. */
+    argv: readonly string[];
+    /**
+     * The session's environment -- THE ONLY place its homes come from beside the config. A host running
+     * this in a Worker passes the Worker's own `process.env` (set by the Worker's `env` option), which is
+     * also what Bash/Monitor/stdio-MCP children inherit.
+     */
+    env: Record<string, string | undefined>;
+    /** stdin as text chunks; framing (NDJSON split) happens here, through the one shared codec. */
+    input: AsyncIterable<string>;
+    /** stdout: receives encoded frames only, never a diagnostic (WS-04 §2/§6). */
+    write: (chunk: string) => void;
+    /** stderr: wiring warnings and the fatal line. Never a frame. */
+    writeErr: (chunk: string) => void;
+    /**
+     * The embedded SIGTERM. On abort: background process groups are killed at once (as `main.ts`'s
+     * SIGTERM handler does), then the engine is told to stop -- the input closes, the running turn is
+     * interrupted -- and this function still resolves only after `runEngine` has RETURNED. That last
+     * part is the contract a host relies on: the transcript lease is keyed by (projectKey, sessionId)
+     * and stamped with the pid, and every Worker shares the host's pid, so the lock cannot tell an old
+     * incarnation from a new one. Only "the old engine has returned" makes a resume safe.
+     */
+    signal?: AbortSignal;
+    /** The workflow worker's spawn command for this session (see `setHostWorkflowWorkerCommand`). */
+    workflowWorkerCommand?: WorkerCommand;
+}
+/**
+ * Run ONE Winter session to completion and return its exit code: `runEngine`'s own code, or `1` when
+ * the session could not start (the fatal line is on `writeErr`, mirroring a child that exits before
+ * init -- WS-04 §6.1). Never throws.
+ */
+export declare function runEmbeddedSession(opts: EmbeddedSessionOptions): Promise<number>;

package/dist/embedded.js

@@ -0,0 +1,9 @@
+import {
+  runEmbeddedSession2
+} from "./index-rkhh0457.js";
+import"./index-584yahed.js";
+import"./index-9qgkpv56.js";
+import"./index-bef62z3r.js";
+export {
+  runEmbeddedSession2 as runEmbeddedSession
+};