@prismatic-io/lux 0.0.1

package/lib/core/tool-events.js

@@ -0,0 +1,242 @@
+import { z } from "zod";
+import { tryParseJson } from "./zod.js";
+export const TOOL_CALL_KIND = "tool-call";
+export const TOOL_RESULT_KIND = "tool-result";
+export const ToolCallPayloadSchema = z
+    .object({
+    name: z.string().min(1),
+    input: z.unknown(),
+    toolUseId: z.string().min(1),
+    parentToolUseId: z.string().min(1).optional(),
+})
+    .loose()
+    .superRefine((payload, ctx) => {
+    if (!Object.hasOwn(payload, "input")) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["input"],
+            message: "input is required",
+        });
+    }
+});
+export const ToolResultPayloadSchema = z
+    .object({
+    name: z.string().min(1),
+    toolUseId: z.string().min(1),
+    content: z.unknown(),
+    structuredContent: z.record(z.string(), z.unknown()).optional(),
+    isError: z.boolean(),
+    text: z.string(),
+    durationMs: z.number().nonnegative().optional(),
+    parentToolUseId: z.string().min(1).optional(),
+})
+    .loose()
+    .superRefine((payload, ctx) => {
+    if (!Object.hasOwn(payload, "content")) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["content"],
+            message: "content is required",
+        });
+    }
+});
+export const ToolOutcomeSummarySchema = z
+    .object({
+    reportedCalls: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    succeeded: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    unresolved: z.number().int().nonnegative(),
+    unmatchedResults: z.number().int().nonnegative(),
+    malformedEvents: z.number().int().nonnegative(),
+})
+    .superRefine((summary, ctx) => {
+    if (summary.reportedCalls < summary.total) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["reportedCalls"],
+            message: "reportedCalls cannot be less than total",
+        });
+    }
+    if (summary.total !== summary.succeeded + summary.failed + summary.unresolved) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["total"],
+            message: "total must equal succeeded + failed + unresolved",
+        });
+    }
+});
+const isProgressKind = (event, kind) => event.type === "progress" && event.kind === kind;
+export const isToolCallEvent = (event) => isProgressKind(event, TOOL_CALL_KIND);
+export const isToolResultEvent = (event) => isProgressKind(event, TOOL_RESULT_KIND);
+export const toolCallProgress = (seq, payload, ts) => ({
+    id: `tc-${payload.toolUseId || seq}`,
+    kind: TOOL_CALL_KIND,
+    payload,
+    ts,
+});
+export const toolResultProgress = (seq, payload, ts) => ({
+    id: `tr-${payload.toolUseId || seq}`,
+    kind: TOOL_RESULT_KIND,
+    payload,
+    ts,
+});
+export const toolEventCalls = (events, name) => events
+    .filter(isToolCallEvent)
+    .map((event) => ToolCallPayloadSchema.safeParse(event.payload).data)
+    .filter((payload) => payload !== undefined)
+    .filter((payload) => name === undefined || payload.name === name);
+export const toolResults = (events, name) => events
+    .filter(isToolResultEvent)
+    .map((event) => ToolResultPayloadSchema.safeParse(event.payload).data)
+    .filter((payload) => payload !== undefined)
+    .filter((payload) => name === undefined || payload.name === name);
+export const malformedToolEventCount = (events, kinds = [
+    TOOL_CALL_KIND,
+    TOOL_RESULT_KIND,
+]) => {
+    const selected = new Set(kinds);
+    return events.filter((event) => {
+        if (event.type !== "progress" || !selected.has(event.kind))
+            return false;
+        const schema = event.kind === TOOL_CALL_KIND ? ToolCallPayloadSchema : ToolResultPayloadSchema;
+        return !schema.safeParse(event.payload).success;
+    }).length;
+};
+export const toolResultValue = (result) => {
+    if (result.structuredContent !== undefined)
+        return result.structuredContent;
+    const parsedText = tryParseJson(result.text);
+    if (Array.isArray(result.content)) {
+        return parsedText !== undefined ? parsedText : result.content;
+    }
+    if (typeof result.content === "string") {
+        const parsedContent = tryParseJson(result.content);
+        return parsedContent !== undefined ? parsedContent : result.content;
+    }
+    if (result.content !== null && result.content !== undefined) {
+        return result.content;
+    }
+    return parsedText !== undefined ? parsedText : result.text;
+};
+/**
+ * Correlate standardized calls with the first later result in the same agent
+ * scope. Evidence without the required correlation fields is ignored.
+ */
+const correlationKey = (toolName, toolUseId, parentToolUseId) => JSON.stringify([parentToolUseId ?? null, toolName, toolUseId]);
+class ToolOutcomeAccumulatorImpl {
+    name;
+    correlatedInvocations = [];
+    pending = new Map();
+    ambiguous = new Map();
+    reportedCalls = 0;
+    succeeded = 0;
+    failed = 0;
+    unresolved = 0;
+    unmatchedResults = 0;
+    malformedEvents = 0;
+    constructor(name) {
+        this.name = name;
+    }
+    add = (event) => {
+        if (isToolCallEvent(event)) {
+            if (this.name === undefined)
+                this.reportedCalls++;
+            const call = ToolCallPayloadSchema.safeParse(event.payload).data;
+            if (!call) {
+                if (this.name === undefined)
+                    this.malformedEvents++;
+                return;
+            }
+            if (this.name !== undefined && call.name !== this.name)
+                return;
+            if (this.name !== undefined)
+                this.reportedCalls++;
+            const index = this.correlatedInvocations.push({ call }) - 1;
+            this.unresolved++;
+            const key = correlationKey(call.name, call.toolUseId, call.parentToolUseId);
+            const ambiguousCalls = this.ambiguous.get(key);
+            if (ambiguousCalls !== undefined) {
+                this.ambiguous.set(key, ambiguousCalls + 1);
+                return;
+            }
+            if (this.pending.has(key)) {
+                this.pending.delete(key);
+                this.ambiguous.set(key, 2);
+                return;
+            }
+            this.pending.set(key, index);
+            return;
+        }
+        if (!isToolResultEvent(event))
+            return;
+        const result = ToolResultPayloadSchema.safeParse(event.payload).data;
+        if (!result) {
+            if (this.name === undefined)
+                this.malformedEvents++;
+            return;
+        }
+        if (this.name !== undefined && result.name !== this.name)
+            return;
+        const key = correlationKey(result.name, result.toolUseId, result.parentToolUseId);
+        const ambiguousCalls = this.ambiguous.get(key);
+        if (ambiguousCalls !== undefined) {
+            this.unmatchedResults++;
+            if (ambiguousCalls === 1)
+                this.ambiguous.delete(key);
+            else
+                this.ambiguous.set(key, ambiguousCalls - 1);
+            return;
+        }
+        const index = this.pending.get(key);
+        if (index === undefined) {
+            this.unmatchedResults++;
+            return;
+        }
+        this.pending.delete(key);
+        const invocation = this.correlatedInvocations[index];
+        if (!invocation) {
+            this.unmatchedResults++;
+            return;
+        }
+        invocation.result = result;
+        this.unresolved--;
+        if (result.isError)
+            this.failed++;
+        else
+            this.succeeded++;
+    };
+    summary = () => ({
+        reportedCalls: this.reportedCalls,
+        total: this.correlatedInvocations.length,
+        succeeded: this.succeeded,
+        failed: this.failed,
+        unresolved: this.unresolved,
+        unmatchedResults: this.unmatchedResults,
+        malformedEvents: this.malformedEvents,
+    });
+    correlation = () => ({
+        invocations: this.correlatedInvocations,
+        unmatchedResults: this.unmatchedResults,
+    });
+}
+export const createToolOutcomeAccumulator = () => new ToolOutcomeAccumulatorImpl();
+export const correlateToolEvents = (events, name) => {
+    const accumulator = new ToolOutcomeAccumulatorImpl(name);
+    for (const event of events)
+        accumulator.add(event);
+    return accumulator.correlation();
+};
+export const toolInvocations = (events, name) => correlateToolEvents(events, name).invocations;
+export const toolInvocationOutcome = (invocation) => {
+    if (!invocation.result)
+        return "unresolved";
+    return invocation.result.isError ? "failed" : "succeeded";
+};
+export const summarizeToolOutcomes = (events) => {
+    const accumulator = createToolOutcomeAccumulator();
+    for (const event of events)
+        accumulator.add(event);
+    return accumulator.summary();
+};
+//# sourceMappingURL=tool-events.js.map

package/lib/core/tool-events.js.map

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

package/lib/core/usage.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+/**
+ * Token accounting. A Lux run spends tokens in three places: the agent
+ * under test (the driver), the answerer playing the user, and the LLM
+ * judge grading the result. Only the first is the thing being measured —
+ * the other two are eval overhead — so usage is tracked per source and
+ * summed at the edges rather than pooled into one number.
+ */
+export declare const TokenUsageSchema: z.ZodObject<{
+    input: z.ZodNumber;
+    output: z.ZodNumber;
+    cacheRead: z.ZodNumber;
+    cacheCreation: z.ZodNumber;
+}, z.core.$strip>;
+export type TokenUsage = z.infer<typeof TokenUsageSchema>;
+/**
+ * One API call's usage, tagged with what the agent did on it — a tool name,
+ * a snippet of its reply — so a per-turn breakdown reads as more than a number.
+ */
+export declare const TurnUsageSchema: z.ZodObject<{
+    input: z.ZodNumber;
+    output: z.ZodNumber;
+    cacheRead: z.ZodNumber;
+    cacheCreation: z.ZodNumber;
+    label: z.ZodExactOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TurnUsage = z.infer<typeof TurnUsageSchema>;
+/**
+ * The vocabulary a turn label is built from: one glyph per facet an API call
+ * exercised. Kept beside the turn model — not in the driver that stamps them
+ * onto labels nor the reporter that documents them in its legend — so the two
+ * cannot drift out of agreement.
+ */
+export declare const TURN_GLYPHS: {
+    readonly thinking: "✻";
+    readonly ask: "?";
+    readonly tool: "⚙";
+    readonly reply: "¶";
+};
+export declare const emptyUsage: () => TokenUsage;
+export declare const addUsage: (a: TokenUsage, b: TokenUsage) => TokenUsage;
+export declare const sumUsage: (usages: readonly TokenUsage[]) => TokenUsage;
+/** Every token the call touched, cached or not. */
+export declare const totalTokens: (u: TokenUsage) => number;
+export declare const isUsageEmpty: (u: TokenUsage) => boolean;
+/** Usage split by who spent it. `agent` is the subject; the rest is harness. */
+export declare const RunUsageSchema: z.ZodObject<{
+    agent: z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        cacheCreation: z.ZodNumber;
+    }, z.core.$strip>;
+    answerer: z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        cacheCreation: z.ZodNumber;
+    }, z.core.$strip>;
+    grading: z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        cacheCreation: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RunUsage = z.infer<typeof RunUsageSchema>;
+export declare const emptyRunUsage: () => RunUsage;
+/** What Lux spent to run the eval, as opposed to what the agent spent. */
+export declare const harnessUsage: (u: RunUsage) => TokenUsage;
+/**
+ * Returns null when the object is absent or carries none of the recognized
+ * usage keys, so a driver can distinguish "reported zero" from "reported
+ * nothing". A partial or malformed report still parses — unrecognized or
+ * missing counts read as 0, per `AgentTokenCountSchema`'s never-fail rule.
+ */
+export declare const parseAgentUsage: (raw: unknown) => TokenUsage | null;
+//# sourceMappingURL=usage.d.ts.map

package/lib/core/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/core/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAO3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;iBAE1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,WAAW;aACtB,QAAQ,EAAE,GAAG;aACb,GAAG,EAAE,GAAG;aACR,IAAI,EAAE,GAAG;aACT,KAAK,EAAE,GAAG;CACF,CAAC;AAEX,eAAO,MAAM,UAAU,QAAO,UAK5B,CAAC;AAEH,eAAO,MAAM,QAAQ,MAAO,UAAU,KAAK,UAAU,KAAG,UAKtD,CAAC;AAEH,eAAO,MAAM,QAAQ,WAAY,SAAS,UAAU,EAAE,KAAG,UAClB,CAAC;AAExC,mDAAmD;AACnD,eAAO,MAAM,WAAW,MAAO,UAAU,KAAG,MACQ,CAAC;AAErD,eAAO,MAAM,YAAY,MAAO,UAAU,KAAG,OAA+B,CAAC;AAE7E,gFAAgF;AAChF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;iBAIzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,eAAO,MAAM,aAAa,QAAO,QAI/B,CAAC;AAEH,0EAA0E;AAC1E,eAAO,MAAM,YAAY,MAAO,QAAQ,KAAG,UAA6C,CAAC;AAiCzF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAS,OAAO,KAAG,UAAU,GAAG,IAI3D,CAAC"}

package/lib/core/usage.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+/**
+ * Token accounting. A Lux run spends tokens in three places: the agent
+ * under test (the driver), the answerer playing the user, and the LLM
+ * judge grading the result. Only the first is the thing being measured —
+ * the other two are eval overhead — so usage is tracked per source and
+ * summed at the edges rather than pooled into one number.
+ */
+export const TokenUsageSchema = z.object({
+    input: z.number().int().nonnegative(),
+    output: z.number().int().nonnegative(),
+    /** Prompt tokens served from the cache. Billed, but far cheaper than `input`. */
+    cacheRead: z.number().int().nonnegative(),
+    /** Prompt tokens written to the cache on this call. */
+    cacheCreation: z.number().int().nonnegative(),
+});
+/**
+ * One API call's usage, tagged with what the agent did on it — a tool name,
+ * a snippet of its reply — so a per-turn breakdown reads as more than a number.
+ */
+export const TurnUsageSchema = TokenUsageSchema.extend({
+    label: z.exactOptional(z.string()),
+});
+/**
+ * The vocabulary a turn label is built from: one glyph per facet an API call
+ * exercised. Kept beside the turn model — not in the driver that stamps them
+ * onto labels nor the reporter that documents them in its legend — so the two
+ * cannot drift out of agreement.
+ */
+export const TURN_GLYPHS = {
+    thinking: "✻",
+    ask: "?",
+    tool: "⚙",
+    reply: "¶",
+};
+export const emptyUsage = () => ({
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheCreation: 0,
+});
+export const addUsage = (a, b) => ({
+    input: a.input + b.input,
+    output: a.output + b.output,
+    cacheRead: a.cacheRead + b.cacheRead,
+    cacheCreation: a.cacheCreation + b.cacheCreation,
+});
+export const sumUsage = (usages) => usages.reduce(addUsage, emptyUsage());
+/** Every token the call touched, cached or not. */
+export const totalTokens = (u) => u.input + u.output + u.cacheRead + u.cacheCreation;
+export const isUsageEmpty = (u) => totalTokens(u) === 0;
+/** Usage split by who spent it. `agent` is the subject; the rest is harness. */
+export const RunUsageSchema = z.object({
+    agent: TokenUsageSchema,
+    answerer: TokenUsageSchema,
+    grading: TokenUsageSchema,
+});
+export const emptyRunUsage = () => ({
+    agent: emptyUsage(),
+    answerer: emptyUsage(),
+    grading: emptyUsage(),
+});
+/** What Lux spent to run the eval, as opposed to what the agent spent. */
+export const harnessUsage = (u) => addUsage(u.answerer, u.grading);
+// Token accounting must never be the reason a run fails to grade.
+const AgentTokenCountSchema = z.number().int().nonnegative().catch(0);
+/**
+ * The snake_case `usage` object the Claude CLI reports (on the
+ * `--output-format json` envelope, and on the final `result` line of a
+ * `stream-json` stream).
+ */
+const AgentUsageSchema = z
+    .object({
+    input_tokens: AgentTokenCountSchema,
+    output_tokens: AgentTokenCountSchema,
+    cache_read_input_tokens: AgentTokenCountSchema,
+    cache_creation_input_tokens: AgentTokenCountSchema,
+})
+    .transform((usage) => ({
+    input: usage.input_tokens,
+    output: usage.output_tokens,
+    cacheRead: usage.cache_read_input_tokens,
+    cacheCreation: usage.cache_creation_input_tokens,
+}));
+const AGENT_USAGE_KEYS = [
+    "input_tokens",
+    "output_tokens",
+    "cache_read_input_tokens",
+    "cache_creation_input_tokens",
+];
+/**
+ * Returns null when the object is absent or carries none of the recognized
+ * usage keys, so a driver can distinguish "reported zero" from "reported
+ * nothing". A partial or malformed report still parses — unrecognized or
+ * missing counts read as 0, per `AgentTokenCountSchema`'s never-fail rule.
+ */
+export const parseAgentUsage = (raw) => {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    if (!AGENT_USAGE_KEYS.some((key) => key in raw))
+        return null;
+    return AgentUsageSchema.safeParse(raw).data ?? null;
+};
+//# sourceMappingURL=usage.js.map

package/lib/core/usage.js.map

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

package/lib/core/wire.d.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { type Answer, type Done, type ErrorEvent, type Interrupt, type Progress, type ReadyState } from "./events.js";
+export declare const WireEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    agentId: z.ZodString;
+    agentVersion: z.ZodExactOptional<z.ZodString>;
+    model: z.ZodExactOptional<z.ZodString>;
+    detail: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    type: z.ZodLiteral<"ready">;
+}, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"ask">;
+    id: z.ZodString;
+    question: z.ZodString;
+    context: z.ZodOptional<z.ZodUnknown>;
+    type: z.ZodLiteral<"interrupt">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"approve">;
+    id: z.ZodString;
+    request: z.ZodString;
+    context: z.ZodOptional<z.ZodUnknown>;
+    type: z.ZodLiteral<"interrupt">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"custom">;
+    id: z.ZodString;
+    payload: z.ZodUnknown;
+    context: z.ZodOptional<z.ZodUnknown>;
+    type: z.ZodLiteral<"interrupt">;
+}, z.core.$strip>], "kind">, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodString;
+    payload: z.ZodUnknown;
+    type: z.ZodLiteral<"progress">;
+    ts: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"done">;
+    summary: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    exitReason: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        "idle-timeout": "idle-timeout";
+        "max-interactions": "max-interactions";
+    }>>;
+    reason: z.ZodString;
+}, z.core.$strip>], "type">;
+export type WireEvent = z.infer<typeof WireEventSchema>;
+export type ParsedDriverEvent = {
+    tag: "ready";
+    ready: ReadyState;
+} | {
+    tag: "interrupt";
+    interrupt: Interrupt;
+} | {
+    tag: "progress";
+    progress: Progress;
+} | {
+    tag: "done";
+    done: Done;
+} | {
+    tag: "error";
+    error: ErrorEvent;
+};
+/**
+ * Parse a single line from a `lux-jsonl` agent. Returns null for empty
+ * lines, malformed JSON, or events that don't match the wire schema.
+ * Validation failures are silent by design — drivers may interleave
+ * non-protocol log lines on stdout.
+ */
+export declare const parseWireEvent: (line: string) => ParsedDriverEvent | null;
+/**
+ * Serialize an Answer to a `lux-jsonl` line (newline-terminated). The
+ * inverse of an agent reading its stdin and dispatching to whatever
+ * pending interrupt the answer is for.
+ */
+export declare const formatWireAnswer: (answer: Answer) => string;
+/**
+ * Parse one stdout line into zero, one, or many Lux driver events. A single
+ * line can carry multiple events — e.g. a Claude Code assistant message with
+ * a text block followed by a tool_use block — so returning an array lets a
+ * driver surface all of them rather than dropping every block after the first.
+ */
+export type ParseEventFn = (line: string) => ParsedDriverEvent | ParsedDriverEvent[] | null;
+export type FormatAnswerFn = (answer: Answer) => string;
+//# sourceMappingURL=wire.d.ts.map

package/lib/core/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/core/wire.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,KAAK,MAAM,EAIX,KAAK,IAAI,EACT,KAAK,UAAU,EAEf,KAAK,SAAS,EACd,KAAK,QAAQ,EAEb,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAqCrB,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAM1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,MAAM,MAAM,iBAAiB,GACzB;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACnC;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GAC1C;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACvC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAC3B;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAwBxC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,SAAU,MAAM,KAAG,iBAAiB,GAAG,IAYjE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,WAAY,MAAM,KAAG,MAUjD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,iBAAiB,GAAG,iBAAiB,EAAE,GAAG,IAAI,CAAC;AAC5F,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC"}

package/lib/core/wire.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { ApproveInterruptSchema, AskInterruptSchema, CustomInterruptSchema, ErrorEventReasonSchema, ProgressSchema, ReadyStateSchema, } from "./events.js";
+/**
+ * The `lux-jsonl` wire protocol. Drivers that talk to a subprocess agent
+ * over stdio (or any line-delimited transport) parse incoming lines with
+ * {@link parseWireEvent} and serialize outgoing answers with
+ * {@link formatWireAnswer}. Drivers that speak a foreign protocol can
+ * import {@link ParsedDriverEvent} and emit it directly.
+ *
+ * Each arm is the internal event schema plus a `type` discriminator. The wire
+ * is looser in two places — `progress.ts` and `error.exitReason` may be omitted
+ * — and those two `z.default()`s are the whole difference.
+ */
+const ReadyEventSchema = ReadyStateSchema.extend({ type: z.literal("ready") });
+const InterruptEventSchema = z.discriminatedUnion("kind", [
+    AskInterruptSchema.extend({ type: z.literal("interrupt") }),
+    ApproveInterruptSchema.extend({ type: z.literal("interrupt") }),
+    CustomInterruptSchema.extend({ type: z.literal("interrupt") }),
+]);
+const ProgressEventSchema = ProgressSchema.extend({
+    type: z.literal("progress"),
+    ts: z.number().default(() => Date.now()),
+});
+const DoneEventSchema = z.object({
+    type: z.literal("done"),
+    summary: z.unknown().optional(),
+});
+const ErrorEventSchema = z.object({
+    type: z.literal("error"),
+    exitReason: ErrorEventReasonSchema.default("error"),
+    reason: z.string(),
+});
+export const WireEventSchema = z.discriminatedUnion("type", [
+    ReadyEventSchema,
+    InterruptEventSchema,
+    ProgressEventSchema,
+    DoneEventSchema,
+    ErrorEventSchema,
+]);
+// Rebuilding (never re-parsing) drops the wire's `type` key; a re-parse
+// against an internal schema would start throwing if that schema gained a
+// required field the wire arm defaults.
+const wireEventToParsed = (event) => {
+    if (event.type === "ready") {
+        const { type: _type, ...ready } = event;
+        return { tag: "ready", ready };
+    }
+    if (event.type === "interrupt") {
+        const { type: _type, ...interrupt } = event;
+        return { tag: "interrupt", interrupt };
+    }
+    if (event.type === "progress") {
+        const { type: _type, ...progress } = event;
+        return { tag: "progress", progress };
+    }
+    if (event.type === "done") {
+        return { tag: "done", done: { exitReason: "done", summary: event.summary } };
+    }
+    return { tag: "error", error: { exitReason: event.exitReason, reason: event.reason } };
+};
+/**
+ * Parse a single line from a `lux-jsonl` agent. Returns null for empty
+ * lines, malformed JSON, or events that don't match the wire schema.
+ * Validation failures are silent by design — drivers may interleave
+ * non-protocol log lines on stdout.
+ */
+export const parseWireEvent = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    const parsed = WireEventSchema.safeParse(raw);
+    if (!parsed.success)
+        return null;
+    return wireEventToParsed(parsed.data);
+};
+/**
+ * Serialize an Answer to a `lux-jsonl` line (newline-terminated). The
+ * inverse of an agent reading its stdin and dispatching to whatever
+ * pending interrupt the answer is for.
+ */
+export const formatWireAnswer = (answer) => {
+    let message;
+    if (answer.kind === "ask") {
+        message = { type: "answer", id: answer.id, text: answer.text };
+    }
+    else if (answer.kind === "approve") {
+        message = { type: answer.approved ? "approve" : "deny", id: answer.id, reason: answer.reason };
+    }
+    else {
+        message = { type: "customToolResponse", id: answer.id, payload: answer.payload };
+    }
+    return `${JSON.stringify(message)}\n`;
+};
+//# sourceMappingURL=wire.js.map

package/lib/core/wire.js.map

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

package/lib/core/zod.d.ts

@@ -0,0 +1,10 @@
+import type { z } from "zod";
+/**
+ * Render a failed parse's issues as one `path: message; path: message` line.
+ * The one place that decides how Lux surfaces schema errors, so every
+ * `Invalid …: <issues>` message the loaders and validators throw reads the
+ * same. `<root>` stands in for an issue at the top level (empty path).
+ */
+export declare const formatZodIssues: (error: z.ZodError) => string;
+export declare const tryParseJson: (text: string) => unknown;
+//# sourceMappingURL=zod.d.ts.map

package/lib/core/zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../../src/core/zod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;GAKG;AACH,eAAO,MAAM,eAAe,UAAW,CAAC,CAAC,QAAQ,KAAG,MACiC,CAAC;AAItF,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,OAM3C,CAAC"}