@guuey/worker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @guuey/worker
+
+The Guuey Worker Protocol v1 types + the tiered worker SDK. Write an agent worker
+in any framework; Guuey runs it, isolates it per end-user, streams it, and scales
+it. You touch only: **read the request → stream your output (text or framework-native events).**
+
+## Zero glue — managed Node base (1a)
+
+Export a handler; the base harness wires it to the protocol.
+
+```js
+import { query } from "@anthropic-ai/claude-agent-sdk";
+export default async (turn) => {
+  for await (const msg of query({ prompt: turn.input, options: {} })) {
+    if (msg.type === "assistant") {
+      for (const block of msg.content) {
+        if (block.type === "text") turn.text(block.text);
+      }
+    }
+  }
+};
+```
+
+## Raw — any language, no SDK
+
+The protocol is deliberately hand-implementable: read NDJSON control messages on
+**stdin (fd 0)**, write NDJSON events on **fd 3**, log freely on stdout/stderr.
+
+```python
+import sys, json, os
+for line in sys.stdin:
+    inv = json.loads(line)   # {type:"invoke", input, identity, fs, history, priorMemory?, priorState?}
+    if inv.get("type") != "invoke": continue
+    # emit framework-native SDK events (the Router normalizes them):
+    os.write(3, (json.dumps({"type":"native","framework":"google-adk","event":{...}}) + "\n").encode())
+    os.write(3, (json.dumps({"type":"done","stopReason":"end_turn","result":"hi"}) + "\n").encode())
+```
+
+## The protocol (v1)
+
+- **fd 0 (stdin), Router→Worker:** `invoke` · `shutdown`
+- **fd 3, Worker→Router:** `text` · `native` · `done` · `error`
+- **stdout/stderr:** your logs — never the protocol.
+- Context is **pushed** in the invoke (`history` · `priorMemory` · `priorState`).
+
+See the design: `docs/superpowers/specs/2026-06-22-worker-platform-northstar-design.md`.

package/dist/emit.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The Worker→Router event emitter (fd 3). Serializes each {@link WorkerEvent} as
+ * one NDJSON line to an injected Writable. The default `serve()` (T4) passes the
+ * fd-3 stream; tests pass an in-memory stream. Each event is written immediately
+ * (one `write` per line) so streaming never stalls behind a buffer.
+ */
+import type { JsonValue, StopReason } from "./protocol.js";
+/** Minimal write interface accepted by {@link createEmitter}. `NodeJS.WritableStream` satisfies this. */
+export interface WriteSink {
+    write(s: string): void;
+}
+export interface Emitter {
+    text(text: string): void;
+    done(result: string, stopReason?: StopReason): void;
+    error(message: string): void;
+    native(framework: string, event: JsonValue): void;
+    /** The SDK-version handshake (additive-optional, §8 item B). Emit at most
+     *  once, before any native/turn event. */
+    hello(framework: string, sdkName: string | null, sdkVersion: string | null): void;
+}
+export declare function createEmitter(out: WriteSink): Emitter;
+//# sourceMappingURL=emit.d.ts.map

package/dist/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAe,MAAM,eAAe,CAAC;AAExE,yGAAyG;AACzG,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACpD,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAClD;8CAC0C;IAC1C,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CACnF;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAWrD"}

package/dist/emit.js

@@ -0,0 +1,12 @@
+export function createEmitter(out) {
+    const write = (ev) => {
+        out.write(JSON.stringify(ev) + "\n");
+    };
+    return {
+        text: (text) => write({ type: "text", text }),
+        done: (result, stopReason = "end_turn") => write({ type: "done", stopReason, result }),
+        error: (message) => write({ type: "error", message }),
+        native: (framework, event) => write({ type: "native", framework, event }),
+        hello: (framework, sdkName, sdkVersion) => write({ type: "hello", framework, sdkName, sdkVersion }),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @guuey/worker — Guuey Worker Protocol v1 types + the tiered worker SDK.
+ * See docs/superpowers/specs/2026-06-22-worker-platform-northstar-design.md §1.
+ */
+export { PROTOCOL_VERSION, type ProtocolVersion, type JsonValue, type AuthMode, type Identity, type Fs, type HistoryMessage, type PriorMemoryRecord, type StopReason, type Invoke, type Shutdown, type ControlMessage, type TextEvent, type DoneEvent, type ErrorEvent, type NativeEvent, type WorkerHelloEvent, type WorkerEvent, } from "./protocol.js";
+export { parseControl, parseEvent, isInvoke, isShutdown, isText, isDone, isError, isNative, isHello, } from "./parse.js";
+export { createEmitter, type Emitter, type WriteSink } from "./emit.js";
+export { serve, serveOn, type ServeOptions } from "./serve.js";
+export { Turn, type WorkerHandler } from "./turn.js";
+export { serveNative, serveNativeOn } from "./serve-native.js";
+export type { NativeEmit, NativeHandler, NativeServeInfo } from "./serve-native.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,EAAE,EACP,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,UAAU,EACV,MAAM,EACN,MAAM,EACN,OAAO,EACP,QAAQ,EACR,OAAO,GACR,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @guuey/worker — Guuey Worker Protocol v1 types + the tiered worker SDK.
+ * See docs/superpowers/specs/2026-06-22-worker-platform-northstar-design.md §1.
+ */
+export { PROTOCOL_VERSION, } from "./protocol.js";
+export { parseControl, parseEvent, isInvoke, isShutdown, isText, isDone, isError, isNative, isHello, } from "./parse.js";
+export { createEmitter } from "./emit.js";
+export { serve, serveOn } from "./serve.js";
+export { Turn } from "./turn.js";
+export { serveNative, serveNativeOn } from "./serve-native.js";

package/dist/lines.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared NDJSON line-reader for the control stream (fd 0). Used by both the
+ * tier-2 managed loop (`serve.ts`) and the native-streaming loop
+ * (`serve-native.ts`) so the two serve tiers read lines identically.
+ */
+import type { Readable } from "node:stream";
+/** Async-iterate NDJSON lines off a Readable. */
+export declare function lines(input: Readable): AsyncIterable<string>;
+//# sourceMappingURL=lines.d.ts.map

package/dist/lines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lines.d.ts","sourceRoot":"","sources":["../src/lines.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,iDAAiD;AACjD,wBAAuB,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAcnE"}

package/dist/lines.js

@@ -0,0 +1,18 @@
+/** Async-iterate NDJSON lines off a Readable. */
+export async function* lines(input) {
+    let buf = "";
+    for await (const chunk of input) {
+        buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        let nl = buf.indexOf("\n");
+        while (nl !== -1) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (line.length > 0)
+                yield line;
+            nl = buf.indexOf("\n");
+        }
+    }
+    const tail = buf.trim();
+    if (tail.length > 0)
+        yield tail;
+}

package/dist/parse.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tier-1 typed interpreter: validate one NDJSON control line (Router→Worker, fd
+ * 0) into a typed {@link ControlMessage}. Hand-rolled guards keep the package
+ * dependency-free. A malformed line throws a clear error (never a silent skip).
+ */
+import type { ControlMessage, DoneEvent, ErrorEvent, Invoke, NativeEvent, Shutdown, TextEvent, WorkerEvent, WorkerHelloEvent } from "./protocol.js";
+export declare function isInvoke(m: ControlMessage): m is Invoke;
+export declare function isShutdown(m: ControlMessage): m is Shutdown;
+export declare function parseControl(line: string): ControlMessage;
+export declare function isText(e: WorkerEvent): e is TextEvent;
+export declare function isDone(e: WorkerEvent): e is DoneEvent;
+export declare function isError(e: WorkerEvent): e is ErrorEvent;
+export declare function isNative(e: WorkerEvent): e is NativeEvent;
+export declare function isHello(e: WorkerEvent): e is WorkerHelloEvent;
+/**
+ * Router-side typed interpreter: validate one NDJSON event line (Worker→Router,
+ * fd 3) into a typed {@link WorkerEvent}. Mirror of {@link parseControl}; a
+ * malformed line throws (never a silent skip).
+ */
+export declare function parseEvent(line: string): WorkerEvent;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAEV,cAAc,EACd,SAAS,EACT,UAAU,EAIV,MAAM,EAEN,WAAW,EAEX,QAAQ,EAER,SAAS,EACT,WAAW,EACX,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAEvB,wBAAgB,QAAQ,CAAC,CAAC,EAAE,cAAc,GAAG,CAAC,IAAI,MAAM,CAEvD;AACD,wBAAgB,UAAU,CAAC,CAAC,EAAE,cAAc,GAAG,CAAC,IAAI,QAAQ,CAE3D;AAyDD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAgCzD;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,IAAI,SAAS,CAErD;AACD,wBAAgB,MAAM,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,IAAI,SAAS,CAErD;AACD,wBAAgB,OAAO,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,IAAI,UAAU,CAEvD;AACD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,IAAI,WAAW,CAEzD;AACD,wBAAgB,OAAO,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,IAAI,gBAAgB,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CA6CpD"}

package/dist/parse.js

@@ -0,0 +1,159 @@
+export function isInvoke(m) {
+    return m.type === "invoke";
+}
+export function isShutdown(m) {
+    return m.type === "shutdown";
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function parseIdentity(v) {
+    if (!isObject(v) || typeof v.userId !== "string") {
+        throw new Error("invoke.identity missing string `userId`");
+    }
+    const authMode = v.authMode === "authenticated" ? "authenticated" : "anonymous";
+    return { userId: v.userId, authMode };
+}
+function parseFs(v) {
+    if (!isObject(v) ||
+        typeof v.app !== "string" ||
+        typeof v.home !== "string" ||
+        typeof v.session !== "string") {
+        throw new Error("invoke.fs missing string `app`/`home`/`session`");
+    }
+    return { app: v.app, home: v.home, session: v.session };
+}
+function parseHistory(v) {
+    if (v === undefined)
+        return [];
+    if (!Array.isArray(v))
+        throw new Error("invoke.history must be an array");
+    return v.map((m) => {
+        if (!isObject(m) || typeof m.text !== "string") {
+            throw new Error("invoke.history entry missing string `text`");
+        }
+        return { role: m.role === "agent" ? "agent" : "user", text: m.text };
+    });
+}
+/**
+ * Parse the optional `priorMemory` push (§1.4). Lenient by design — a malformed
+ * entry (no `value`, or a non-object) is DROPPED rather than throwing, so a
+ * stray memory record never fails an otherwise-valid turn. Returns `undefined`
+ * when absent or when no entry survives (so the field stays off the Invoke).
+ */
+function parsePriorMemory(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = [];
+    for (const entry of v) {
+        if (isObject(entry) && "value" in entry) {
+            out.push({
+                value: entry.value,
+                ...(typeof entry.key === "string" ? { key: entry.key } : {}),
+            });
+        }
+    }
+    return out.length > 0 ? out : undefined;
+}
+export function parseControl(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        throw new Error(`non-JSON control line: ${line.slice(0, 200)}`);
+    }
+    if (!isObject(raw)) {
+        throw new Error(`control line is not an object: ${line.slice(0, 200)}`);
+    }
+    switch (raw.type) {
+        case "invoke": {
+            if (typeof raw.input !== "string")
+                throw new Error("invoke missing string `input`");
+            const priorMemory = parsePriorMemory(raw.priorMemory);
+            return {
+                type: "invoke",
+                input: raw.input,
+                identity: parseIdentity(raw.identity),
+                fs: parseFs(raw.fs),
+                history: parseHistory(raw.history),
+                // §1.4 push-by-value context — additive, both optional. `priorState` uses
+                // a `!== undefined` gate (not truthiness) so a falsy blob (null/0/"") is
+                // preserved; `priorMemory` is omitted when empty/absent.
+                ...(priorMemory ? { priorMemory } : {}),
+                ...(raw.priorState !== undefined ? { priorState: raw.priorState } : {}),
+            };
+        }
+        case "shutdown":
+            return { type: "shutdown" };
+        default:
+            throw new Error(`unknown control message type: ${String(raw.type)}`);
+    }
+}
+export function isText(e) {
+    return e.type === "text";
+}
+export function isDone(e) {
+    return e.type === "done";
+}
+export function isError(e) {
+    return e.type === "error";
+}
+export function isNative(e) {
+    return e.type === "native";
+}
+export function isHello(e) {
+    return e.type === "hello";
+}
+/**
+ * Router-side typed interpreter: validate one NDJSON event line (Worker→Router,
+ * fd 3) into a typed {@link WorkerEvent}. Mirror of {@link parseControl}; a
+ * malformed line throws (never a silent skip).
+ */
+export function parseEvent(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        throw new Error(`non-JSON event line: ${line.slice(0, 200)}`);
+    }
+    if (!isObject(raw)) {
+        throw new Error(`event line is not an object: ${line.slice(0, 200)}`);
+    }
+    switch (raw.type) {
+        case "text": {
+            if (typeof raw.text !== "string")
+                throw new Error("text event missing string `text`");
+            return { type: "text", text: raw.text };
+        }
+        case "done": {
+            const stopReason = raw.stopReason === "max_turns" || raw.stopReason === "error" ? raw.stopReason : "end_turn";
+            const result = typeof raw.result === "string" ? raw.result : "";
+            return { type: "done", stopReason, result };
+        }
+        case "error": {
+            const message = typeof raw.message === "string" ? raw.message : "unknown worker error";
+            return { type: "error", message };
+        }
+        case "native": {
+            if (typeof raw.framework !== "string") {
+                throw new Error("native event missing string `framework`");
+            }
+            if (raw.event === undefined) {
+                throw new Error("native event missing `event`");
+            }
+            return { type: "native", framework: raw.framework, event: raw.event };
+        }
+        case "hello": {
+            if (typeof raw.framework !== "string") {
+                throw new Error("hello event missing string `framework`");
+            }
+            const sdkName = typeof raw.sdkName === "string" ? raw.sdkName : null;
+            const sdkVersion = typeof raw.sdkVersion === "string" ? raw.sdkVersion : null;
+            return { type: "hello", framework: raw.framework, sdkName, sdkVersion };
+        }
+        default:
+            throw new Error(`unknown event type: ${String(raw.type)}`);
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Guuey Worker Protocol v1 — the frozen, versioned types the Router and a Worker
+ * exchange. Types ARE the protocol's source of truth (per-language SDKs derive
+ * from these). See the north-star design §1.
+ *
+ *   Router → Worker  (fd 0 / stdin):  ControlMessage  (invoke | shutdown)
+ *   Worker → Router  (fd 3):          WorkerEvent      (text | done | error)
+ *   stdout (1) + stderr (2):          the builder's own logs — not the protocol.
+ */
+/** v1 ≡ the worker-facing half of Guuey Router v1 (pinned via `runtime.router`). */
+export declare const PROTOCOL_VERSION: "v1";
+export type ProtocolVersion = typeof PROTOCOL_VERSION;
+/** A JSON value — the precise parse target for NDJSON control/event lines
+ *  (NOT `unknown`: a parsed line has no static shape yet, but it IS JSON). */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type AuthMode = "anonymous" | "authenticated";
+/** Router-vouched end-user identity (the Worker writes zero auth code). */
+export interface Identity {
+    userId: string;
+    authMode: AuthMode;
+}
+/** The three GuueyFS layer mounts the Worker reads/writes. */
+export interface Fs {
+    app: string;
+    home: string;
+    session: string;
+}
+export interface HistoryMessage {
+    role: "user" | "agent";
+    text: string;
+}
+/**
+ * One prior-memory record pushed by value on the invoke (§1.4). A minimal,
+ * dependency-free projection of the Router's `AgMemoryRecord` — the worker reads
+ * only `key`/`value` for its `<thread_memory>` preamble. `value` is required
+ * (the fold seeds it); `key` is optional (unkeyed records exist).
+ */
+export interface PriorMemoryRecord {
+    key?: string;
+    value: JsonValue;
+}
+export type StopReason = "end_turn" | "max_turns" | "error";
+/** Start a turn. Carries the pushed context (identity, fs, a recent history
+ *  window — the full transcript is at `/session/.guuey/history.jsonl`).
+ *
+ *  `priorMemory`/`priorState` are the §1.4 push-by-value context the worker
+ *  renders into its system-prompt preamble (thread memory + working state).
+ *  Both optional: an early-thread invoke carries neither. */
+export interface Invoke {
+    type: "invoke";
+    input: string;
+    identity: Identity;
+    fs: Fs;
+    history: HistoryMessage[];
+    /** Thread-scoped memory folded from prior turns (the `<thread_memory>` preamble). */
+    priorMemory?: PriorMemoryRecord[];
+    /** Prior working-state blob carried from the previous turn (the `<working_state>` preamble). */
+    priorState?: JsonValue;
+}
+/** Graceful termination (also signalled by stdin EOF). */
+export interface Shutdown {
+    type: "shutdown";
+}
+export type ControlMessage = Invoke | Shutdown;
+/** Stream a chunk of assistant output. */
+export interface TextEvent {
+    type: "text";
+    text: string;
+}
+/** Terminal success. `result` is the turn's final text. */
+export interface DoneEvent {
+    type: "done";
+    stopReason: StopReason;
+    result: string;
+}
+/** Terminal failure. */
+export interface ErrorEvent {
+    type: "error";
+    message: string;
+}
+/**
+ * Pass-through carrier for framework-native SDK events (fd-3).
+ * The Worker emits these opaquely; the Router dispatches to the matching
+ * `@silverprotocol/<framework>` normalizer.
+ *
+ * `framework` is typed as `string` rather than the `AgentFramework` enum from
+ * `@guuey/config` to keep this package dependency-free. The Router validates
+ * `framework` against the real enum before dispatching.
+ */
+export interface NativeEvent {
+    readonly type: "native";
+    /** The framework whose native event this is — Router picks the normalizer. */
+    readonly framework: string;
+    /** One native SDK event, opaque JSON; only the Router's normalizer reads it. */
+    readonly event: JsonValue;
+}
+/**
+ * Additive-optional in protocol v1 (the SDK-version handshake, model-release
+ * playbook §8 item B). A worker MAY emit this once, before any native/turn
+ * event, to report its own SDK provenance. The Router treats it as Router-plane
+ * ONLY: never forwarded to the SSE client, never fed to a `@silverprotocol/*`
+ * normalizer (it is not an AgJSON-eligible event) — just logged + carried into
+ * the invoke's completion telemetry. Absence is fully tolerated (older workers
+ * that predate this event, or a builder's own `serve()`-based worker that never
+ * emits it): the Router simply has no SDK provenance to log for that invoke.
+ */
+export interface WorkerHelloEvent {
+    readonly type: "hello";
+    /** The framework this worker runs — matches `NativeEvent.framework`. */
+    readonly framework: string;
+    /** The SDK package name, e.g. `"@anthropic-ai/claude-agent-sdk"`; `null` when unknown/inapplicable. */
+    readonly sdkName: string | null;
+    /** The SDK's installed version, resolved at RUNTIME (never a hardcoded literal); `null` when unresolvable. */
+    readonly sdkVersion: string | null;
+}
+export type WorkerEvent = TextEvent | DoneEvent | ErrorEvent | NativeEvent | WorkerHelloEvent;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,EAAG,IAAa,CAAC;AAC9C,MAAM,MAAM,eAAe,GAAG,OAAO,gBAAgB,CAAC;AAEtD;8EAC8E;AAC9E,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,eAAe,CAAC;AACrD,2EAA2E;AAC3E,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;CACpB;AACD,8DAA8D;AAC9D,MAAM,WAAW,EAAE;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AACD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB;AACD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC;AAI5D;;;;;6DAK6D;AAC7D,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,EAAE,EAAE,EAAE,CAAC;IACP,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,qFAAqF;IACrF,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,gGAAgG;IAChG,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB;AACD,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,UAAU,CAAC;CAClB;AACD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,CAAC;AAI/C,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AACD,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AACD;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AACD;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uGAAuG;IACvG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,8GAA8G;IAC9G,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AACD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,gBAAgB,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,11 @@
+/**
+ * Guuey Worker Protocol v1 — the frozen, versioned types the Router and a Worker
+ * exchange. Types ARE the protocol's source of truth (per-language SDKs derive
+ * from these). See the north-star design §1.
+ *
+ *   Router → Worker  (fd 0 / stdin):  ControlMessage  (invoke | shutdown)
+ *   Worker → Router  (fd 3):          WorkerEvent      (text | done | error)
+ *   stdout (1) + stderr (2):          the builder's own logs — not the protocol.
+ */
+/** v1 ≡ the worker-facing half of Guuey Router v1 (pinned via `runtime.router`). */
+export const PROTOCOL_VERSION = "v1";

package/dist/serve-native.d.ts

@@ -0,0 +1,18 @@
+import type { Invoke, JsonValue } from "./protocol.js";
+import type { ServeOptions } from "./serve.js";
+export interface NativeEmit {
+    native(event: JsonValue): void;
+    text(chunk: string): void;
+}
+export type NativeHandler = (invoke: Invoke, emit: NativeEmit) => Promise<string | void> | string | void;
+export interface NativeServeInfo {
+    framework: string;
+    sdkName?: string | null;
+    sdkVersion?: string | null;
+}
+export declare function serveNativeOn(handler: NativeHandler, info: NativeServeInfo, opts: ServeOptions): Promise<void>;
+/** The public entry: wire stdin (fd 0) + an fd-3 Writable, then run the loop. */
+export declare function serveNative(handler: NativeHandler, info: NativeServeInfo, opts?: {
+    idleMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=serve-native.d.ts.map

package/dist/serve-native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-native.d.ts","sourceRoot":"","sources":["../src/serve-native.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AACD,MAAM,MAAM,aAAa,GAAG,CAC1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,KACb,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;AAC5C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CACzB,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,eAAe,EACrB,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/serve-native.js

@@ -0,0 +1,56 @@
+/**
+ * Native-streaming serve loop: mirrors `serve.ts`'s line-reading, idle-timeout,
+ * and shutdown handling exactly, but the per-invoke body emits opaque
+ * framework-native events (`emit.native`) alongside text, instead of driving a
+ * `Turn`. Lets a template worker emit `hello` → `native`* → `done` per invoke,
+ * like `@guuey/host` does.
+ */
+import { createWriteStream } from "node:fs";
+import { createEmitter } from "./emit.js";
+import { lines } from "./lines.js";
+import { isInvoke, isShutdown, parseControl } from "./parse.js";
+export async function serveNativeOn(handler, info, opts) {
+    const emitter = createEmitter(opts.output);
+    const idleMs = opts.idleMs ?? 5 * 60_000;
+    let idle;
+    const arm = () => {
+        if (idle)
+            clearTimeout(idle);
+        idle = setTimeout(() => opts.input.push(null), idleMs);
+        if (idle.unref)
+            idle.unref();
+    };
+    arm();
+    for await (const line of lines(opts.input)) {
+        arm();
+        const msg = parseControl(line);
+        if (isShutdown(msg))
+            break;
+        if (!isInvoke(msg))
+            continue;
+        emitter.hello(info.framework, info.sdkName ?? null, info.sdkVersion ?? null);
+        try {
+            const scoped = {
+                native: (event) => emitter.native(info.framework, event),
+                text: (chunk) => emitter.text(chunk),
+            };
+            const result = await handler(msg, scoped);
+            emitter.done(typeof result === "string" ? result : "", "end_turn");
+        }
+        catch (e) {
+            emitter.error(e instanceof Error ? e.message : String(e));
+        }
+    }
+    if (idle)
+        clearTimeout(idle);
+}
+/** The public entry: wire stdin (fd 0) + an fd-3 Writable, then run the loop. */
+export function serveNative(handler, info, opts) {
+    // fd 3 is the write end of the pipe the Router created at spawn.
+    const output = createWriteStream("", { fd: 3 });
+    return serveNativeOn(handler, info, {
+        input: process.stdin,
+        output,
+        ...(opts?.idleMs ? { idleMs: opts.idleMs } : {}),
+    });
+}

package/dist/serve.d.ts

@@ -0,0 +1,14 @@
+import type { Readable, Writable } from "node:stream";
+import { type WorkerHandler } from "./turn.js";
+export interface ServeOptions {
+    input: Readable;
+    output: Writable;
+    /** Stop the loop after this many ms with no control input (default 5 min). */
+    idleMs?: number;
+}
+export declare function serveOn(handler: WorkerHandler, opts: ServeOptions): Promise<void>;
+/** The public entry: wire stdin (fd 0) + an fd-3 Writable, then run the loop. */
+export declare function serve(handler: WorkerHandler, opts?: {
+    idleMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAItD,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BvF;AAED,iFAAiF;AACjF,wBAAgB,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvF"}

package/dist/serve.js

@@ -0,0 +1,61 @@
+/**
+ * Tier-2 managed loop. Reads the NDJSON control stream (fd 0), drives the handler
+ * per `invoke`, emits events on fd 3, and handles `shutdown`/EOF and an idle
+ * timeout. `serveOn` is the injectable, unit-testable core; `serve` defaults the
+ * streams to `process.stdin` + an fd-3 Writable.
+ *
+ * Turns are inherently sequential — the handler for an `invoke` is `await`ed
+ * inline before the reader advances to the next control line — so no chaining or
+ * concurrent reader is needed.
+ */
+import { createWriteStream } from "node:fs";
+import { createEmitter } from "./emit.js";
+import { lines } from "./lines.js";
+import { isInvoke, isShutdown, parseControl } from "./parse.js";
+import { Turn } from "./turn.js";
+export async function serveOn(handler, opts) {
+    const emit = createEmitter(opts.output);
+    const idleMs = opts.idleMs ?? 5 * 60_000;
+    let idle;
+    const arm = () => {
+        if (idle)
+            clearTimeout(idle);
+        idle = setTimeout(() => opts.input.push(null), idleMs);
+        if (idle.unref)
+            idle.unref();
+    };
+    arm();
+    for await (const line of lines(opts.input)) {
+        arm();
+        const msg = parseControl(line);
+        if (isShutdown(msg))
+            break;
+        if (!isInvoke(msg))
+            continue;
+        // Run the turn inline: turns are sequential, so the next control line is read
+        // only after this handler settles.
+        let acc = "";
+        const turn = new Turn(msg.input, msg.identity, msg.fs, msg.history, emit, (chunk) => {
+            acc += chunk;
+        });
+        try {
+            const result = await handler(turn);
+            emit.done(typeof result === "string" ? result : acc);
+        }
+        catch (err) {
+            emit.error(err instanceof Error ? err.message : String(err));
+        }
+    }
+    if (idle)
+        clearTimeout(idle);
+}
+/** The public entry: wire stdin (fd 0) + an fd-3 Writable, then run the loop. */
+export function serve(handler, opts) {
+    // fd 3 is the write end of the pipe the Router created at spawn.
+    const output = createWriteStream("", { fd: 3 });
+    return serveOn(handler, {
+        input: process.stdin,
+        output,
+        ...(opts?.idleMs ? { idleMs: opts.idleMs } : {}),
+    });
+}

package/dist/turn.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The `Turn` handed to a worker handler — the entire surface a builder touches:
+ * the pushed context (`input`/`identity`/`fs`/`history`) plus `text()` to stream.
+ * Nothing Guuey-specific beyond this.
+ */
+import type { Fs, HistoryMessage, Identity } from "./protocol.js";
+import type { Emitter } from "./emit.js";
+export declare class Turn {
+    readonly input: string;
+    readonly identity: Identity;
+    readonly fs: Fs;
+    readonly history: HistoryMessage[];
+    private readonly emit;
+    private readonly onText;
+    constructor(input: string, identity: Identity, fs: Fs, history: HistoryMessage[], emit: Emitter, onText: (chunk: string) => void);
+    /** Stream a chunk of assistant output (also accumulated into `done.result`). */
+    text(chunk: string): void;
+}
+/** A worker handler: do the work, return the final result string (or rely on the
+ *  accumulated `turn.text(...)`). */
+export type WorkerHandler = (turn: Turn) => Promise<string | void> | string | void;
+//# sourceMappingURL=turn.d.ts.map

package/dist/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../src/turn.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,EAAE,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,qBAAa,IAAI;IAEb,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAC3B,QAAQ,CAAC,EAAE,EAAE,EAAE;IACf,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBALd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ,EAClB,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,cAAc,EAAE,EACjB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI;IAGlD,gFAAgF;IAChF,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAI1B;AAED;qCACqC;AACrC,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC"}

package/dist/turn.js

@@ -0,0 +1,21 @@
+export class Turn {
+    input;
+    identity;
+    fs;
+    history;
+    emit;
+    onText;
+    constructor(input, identity, fs, history, emit, onText) {
+        this.input = input;
+        this.identity = identity;
+        this.fs = fs;
+        this.history = history;
+        this.emit = emit;
+        this.onText = onText;
+    }
+    /** Stream a chunk of assistant output (also accumulated into `done.result`). */
+    text(chunk) {
+        this.onText(chunk);
+        this.emit.text(chunk);
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@guuey/worker",
+  "version": "0.1.0",
+  "description": "Guuey Worker Protocol v1 — the Router↔Worker contract types and the tiered worker SDK (typed interpreter + serve loop).",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "guuey",
+    "agent",
+    "worker",
+    "protocol",
+    "sdk"
+  ],
+  "homepage": "https://guuey.com",
+  "bugs": {
+    "url": "https://github.com/loqu-co/guuey/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withguuey/guuey-sdks.git",
+    "directory": "packages/worker"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}