@oneharness/sdk 0.3.23 → 0.4.0

package/dist/generated/zod.d.ts

@@ -6,8 +6,11 @@ import type { HistoryList, HistorySessionSummary } from "./history-list.js";
 import type { HistoryListOptions } from "./history-list-options.js";
 import type { HistoryLookup, HistoryLookupByLast, HistoryLookupBySession } from "./history-lookup.js";
 import type { HistoryRecords } from "./history-records.js";
-import type { PermissionMode, RunOptions } from "./options.js";
+import type { HistoryStreamEnvelope } from "./history-stream-envelope.js";
+import type { HistoryWatchOptions } from "./history-watch-options.js";
+import type { HistoryLabels, PermissionMode, RunOptions } from "./options.js";
 import type { HarnessInfo, ListReport, ModeInfo } from "./registry.js";
+import type { RunStreamEnvelope } from "./run-stream-envelope.js";
 export type BatchStrategy = BatchReport["strategy"];
 export type ModeHeadless = ModeInfo["headless"];
 export type SessionPhase = SessionReport["phase"];
@@ -20,6 +23,7 @@ export declare const FailureKindSchema: z.ZodType<FailureKind>;
 export declare const FallThroughSchema: z.ZodType<FallThrough>;
 export declare const FallbackReportSchema: z.ZodType<FallbackReport>;
 export declare const HarnessInfoSchema: z.ZodType<HarnessInfo>;
+export declare const HistoryLabelsSchema: z.ZodType<HistoryLabels>;
 export declare const HistoryListSchema: z.ZodType<HistoryList>;
 export declare const HistoryListOptionsSchema: z.ZodType<HistoryListOptions>;
 export declare const HistoryLookupSchema: z.ZodType<HistoryLookup>;
@@ -28,6 +32,8 @@ export declare const HistoryLookupBySessionSchema: z.ZodType<HistoryLookupBySess
 export declare const HistoryRecordSchema: z.ZodType<HistoryRecord>;
 export declare const HistoryRecordsSchema: z.ZodType<HistoryRecords>;
 export declare const HistorySessionSummarySchema: z.ZodType<HistorySessionSummary>;
+export declare const HistoryStreamEnvelopeSchema: z.ZodType<HistoryStreamEnvelope>;
+export declare const HistoryWatchOptionsSchema: z.ZodType<HistoryWatchOptions>;
 export declare const ListReportSchema: z.ZodType<ListReport>;
 export declare const ModeHeadlessSchema: z.ZodType<ModeHeadless>;
 export declare const ModeInfoSchema: z.ZodType<ModeInfo>;
@@ -36,6 +42,7 @@ export declare const PermissionModeSchema: z.ZodType<PermissionMode>;
 export declare const RunOptionsSchema: z.ZodType<RunOptions>;
 export declare const RunReportSchema: z.ZodType<RunReport>;
 export declare const RunResultSchema: z.ZodType<RunResult>;
+export declare const RunStreamEnvelopeSchema: z.ZodType<RunStreamEnvelope>;
 export declare const SessionPhaseSchema: z.ZodType<SessionPhase>;
 export declare const SessionReportSchema: z.ZodType<SessionReport>;
 export declare const StatusSchema: z.ZodType<Status>;

package/dist/generated/zod.js

@@ -70,6 +70,19 @@ export const HarnessInfoSchema = z.looseObject({
     supports_system_file: z.boolean().refine((value) => value !== undefined, { message: "Required" }),
     sync_file: z.union([z.string(), z.null()]).refine((value) => value !== undefined, { message: "Required" }),
 });
+export const HistoryLabelsSchema = z.record(z
+    .string()
+    .regex(new RegExp("^[A-Za-z0-9]", "u"))
+    .refine((value) => [...value].length <= 64, { message: "Too long: expected at most 64 characters" })
+    .refine((value) => !new RegExp("[^A-Za-z0-9._-]", "u").test(value), {
+    message: "Invalid string: must not contain [^A-Za-z0-9._-]",
+}), z
+    .string()
+    .min(1)
+    .refine((value) => [...value].length <= 256, { message: "Too long: expected at most 256 characters" })
+    .refine((value) => !new RegExp("[\\u0000-\\u001f\\u007f-\\u009f]", "u").test(value), {
+    message: "Invalid string: must not contain [\\u0000-\\u001f\\u007f-\\u009f]",
+}));
 export const HistoryListSchema = z.array(z.lazy(() => HistorySessionSummarySchema));
 export const HistoryListOptionsSchema = z.strictObject({
     allProjects: z.boolean().optional(),
@@ -107,6 +120,13 @@ export const HistoryRecordSchema = z.looseObject({
         .union([z.lazy(() => FailureKindSchema), z.null()])
         .refine((value) => value !== undefined, { message: "Required" }),
     harness: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    history_id: z
+        .string()
+        .min(36)
+        .regex(new RegExp("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "u"))
+        .refine((value) => [...value].length <= 36, { message: "Too long: expected at most 36 characters" })
+        .refine((value) => value !== undefined, { message: "Required" }),
+    labels: z.lazy(() => HistoryLabelsSchema).optional(),
     model: z.union([z.string(), z.null()]).refine((value) => value !== undefined, { message: "Required" }),
     name: z.string().refine((value) => value !== undefined, { message: "Required" }),
     permission_mode: z.lazy(() => PermissionModeSchema).refine((value) => value !== undefined, { message: "Required" }),
@@ -125,6 +145,7 @@ export const HistoryRecordsSchema = z.array(z.lazy(() => HistoryRecordSchema));
 export const HistorySessionSummarySchema = z.looseObject({
     harnesses: z.array(z.string()).refine((value) => value !== undefined, { message: "Required" }),
     id: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    labels: z.lazy(() => HistoryLabelsSchema).optional(),
     name: z.string().refine((value) => value !== undefined, { message: "Required" }),
     path: z.string().refine((value) => value !== undefined, { message: "Required" }),
     project: z.string().refine((value) => value !== undefined, { message: "Required" }),
@@ -134,6 +155,22 @@ export const HistorySessionSummarySchema = z.looseObject({
         .refine((value) => value !== undefined, { message: "Required" }),
     started: z.string().refine((value) => value !== undefined, { message: "Required" }),
 });
+export const HistoryStreamEnvelopeSchema = z.looseObject({
+    record: z.lazy(() => HistoryRecordSchema).refine((value) => value !== undefined, { message: "Required" }),
+    type: z.literal("record").refine((value) => value !== undefined, { message: "Required" }),
+});
+export const HistoryWatchOptionsSchema = z.strictObject({
+    after: z
+        .string()
+        .min(36)
+        .regex(new RegExp("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "u"))
+        .refine((value) => [...value].length <= 36, { message: "Too long: expected at most 36 characters" })
+        .optional(),
+    allProjects: z.boolean().optional(),
+    historyDir: z.string().optional(),
+    labels: z.lazy(() => HistoryLabelsSchema).optional(),
+    project: z.string().optional(),
+});
 export const ListReportSchema = z.looseObject({
     harnesses: z.array(z.lazy(() => HarnessInfoSchema)).refine((value) => value !== undefined, { message: "Required" }),
     schema_version: z.string().refine((value) => value !== undefined, { message: "Required" }),
@@ -165,6 +202,7 @@ export const RunOptionsSchema = z.strictObject({
     harnesses: z.array(z.string()).optional(),
     history: z.boolean().optional(),
     historyDir: z.string().optional(),
+    historyLabels: z.lazy(() => HistoryLabelsSchema).optional(),
     historyName: z.string().optional(),
     mode: z.lazy(() => PermissionModeSchema).optional(),
     models: z.array(z.string()).optional(),
@@ -240,6 +278,16 @@ export const RunResultSchema = z.looseObject({
     usage: z.lazy(() => UsageSchema).refine((value) => value !== undefined, { message: "Required" }),
     usage_source: z.union([z.string(), z.null()]).refine((value) => value !== undefined, { message: "Required" }),
 });
+export const RunStreamEnvelopeSchema = z.union([
+    z.looseObject({
+        event: z.lazy(() => ActionEventSchema).refine((value) => value !== undefined, { message: "Required" }),
+        type: z.literal("event").refine((value) => value !== undefined, { message: "Required" }),
+    }),
+    z.looseObject({
+        report: z.lazy(() => RunReportSchema).refine((value) => value !== undefined, { message: "Required" }),
+        type: z.literal("result").refine((value) => value !== undefined, { message: "Required" }),
+    }),
+]);
 export const SessionPhaseSchema = z.union([z.literal("create"), z.literal("continue")]);
 export const SessionReportSchema = z.looseObject({
     name: z.string().refine((value) => value !== undefined, { message: "Required" }),

package/dist/index.d.ts

@@ -4,8 +4,11 @@ import type { HistoryRecord } from "./generated/history.js";
 import type { HistorySessionSummary } from "./generated/history-list.js";
 import type { HistoryListOptions } from "./generated/history-list-options.js";
 import type { HistoryLookup } from "./generated/history-lookup.js";
+import type { HistoryStreamEnvelope } from "./generated/history-stream-envelope.js";
+import type { HistoryWatchOptions } from "./generated/history-watch-options.js";
 import type { RunOptions } from "./generated/options.js";
 import type { HarnessInfo } from "./generated/registry.js";
+import type { RunStreamEnvelope } from "./generated/run-stream-envelope.js";
 export type { ActionEvent, BatchReport, FailureKind, FallbackReport, FallThrough, OutputFormat, RunReport, RunResult, SessionReport, Status, Usage, } from "./generated/contracts.js";
 export type { DetectInfo, DetectReport } from "./generated/detection.js";
 export type { HistoryRecord } from "./generated/history.js";
@@ -13,7 +16,10 @@ export type { HistoryList, HistorySessionSummary, } from "./generated/history-li
 export type { HistoryListOptions } from "./generated/history-list-options.js";
 export type { HistoryLookup, HistoryLookupByLast, HistoryLookupBySession, } from "./generated/history-lookup.js";
 export type { HistoryRecords } from "./generated/history-records.js";
+export type { HistoryStreamEnvelope } from "./generated/history-stream-envelope.js";
+export type { HistoryWatchOptions } from "./generated/history-watch-options.js";
 export type { PermissionMode, RunOptions } from "./generated/options.js";
+export type { RunStreamEnvelope } from "./generated/run-stream-envelope.js";
 export type Detection = DetectInfo;
 export type { HarnessInfo, ListReport, ModeInfo, } from "./generated/registry.js";
 export * from "./generated/zod.js";
@@ -22,12 +28,24 @@ export type OneHarnessOptions = {
     executableArgs?: readonly string[];
     env?: Readonly<Record<string, string>>;
 };
+/** A non-zero exit from the oneharness subprocess. */
+export declare class OneHarnessProcessError extends Error {
+    readonly exitCode: number | null;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number | null, stderr: string);
+}
+/** A history lookup or watch cursor that the CLI could not resolve. */
+export declare class HistoryNotFoundError extends OneHarnessProcessError {
+    constructor(message: string, exitCode: number | null, stderr: string);
+}
 export declare class OneHarness {
     private readonly options;
     constructor(options?: OneHarnessOptions);
     run(options: RunOptions): Promise<RunReport>;
+    runStream(options: RunOptions): AsyncGenerator<RunStreamEnvelope>;
     list(): Promise<HarnessInfo[]>;
     detect(harnesses?: readonly string[]): Promise<Detection[]>;
     history(lookup: HistoryLookup): Promise<HistoryRecord[]>;
     historyList(options?: HistoryListOptions): Promise<HistorySessionSummary[]>;
+    historyWatch(options?: HistoryWatchOptions): AsyncGenerator<HistoryStreamEnvelope>;
 }

package/dist/index.js

@@ -1,7 +1,26 @@
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
-import { DetectReportSchema, HistoryListOptionsSchema, HistoryListSchema, HistoryLookupSchema, HistoryRecordsSchema, ListReportSchema, RunOptionsSchema, RunReportSchema, } from "./generated/zod.js";
+import { createInterface } from "node:readline";
+import { DetectReportSchema, HistoryListOptionsSchema, HistoryListSchema, HistoryLookupSchema, HistoryRecordsSchema, HistoryStreamEnvelopeSchema, HistoryWatchOptionsSchema, ListReportSchema, RunOptionsSchema, RunReportSchema, RunStreamEnvelopeSchema, } from "./generated/zod.js";
 export * from "./generated/zod.js";
+/** A non-zero exit from the oneharness subprocess. */
+export class OneHarnessProcessError extends Error {
+    exitCode;
+    stderr;
+    constructor(message, exitCode, stderr) {
+        super(message);
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = "OneHarnessProcessError";
+    }
+}
+/** A history lookup or watch cursor that the CLI could not resolve. */
+export class HistoryNotFoundError extends OneHarnessProcessError {
+    constructor(message, exitCode, stderr) {
+        super(message, exitCode, stderr);
+        this.name = "HistoryNotFoundError";
+    }
+}
 function parseContract(schema, value, label) {
     const parsed = schema.safeParse(value);
     if (parsed.success)
@@ -44,22 +63,126 @@ async function invokeWith(options, args, cwd, acceptJsonOnNonzero = false) {
         child.on("error", reject);
         child.on("close", (code) => {
             if (code !== 0 && !acceptJsonOnNonzero)
-                return reject(new Error(`oneharness exited ${code}: ${stderr.trim()}`));
+                return reject(processError(code, stderr));
             try {
                 resolve(JSON.parse(stdout));
             }
             catch (error) {
                 if (code !== 0)
-                    return reject(new Error(`oneharness exited ${code}: ${stderr.trim()}`));
+                    return reject(processError(code, stderr));
                 reject(new Error(`oneharness returned invalid JSON: ${String(error)}`));
             }
         });
     });
 }
+function processError(code, stderr) {
+    return new OneHarnessProcessError(`oneharness exited ${code}: ${stderr.trim()}`, code, stderr);
+}
+function historyNotFound(error) {
+    return (error instanceof OneHarnessProcessError &&
+        (error.exitCode === 1 || error.stderr.includes("was not found")));
+}
+function asHistoryNotFound(error) {
+    return new HistoryNotFoundError(error.message, error.exitCode, error.stderr);
+}
+async function* invokeStreamWith(options, args, schema, label, cwd, historyStream = false) {
+    const bin = executable(options);
+    const child = spawn(bin.command, [...bin.prefix, ...args], {
+        cwd,
+        env: { ...process.env, ...options.env },
+        windowsHide: true,
+    });
+    let stderr = "";
+    let spawnError;
+    let closed = false;
+    child.stderr
+        .setEncoding("utf8")
+        .on("data", (chunk) => (stderr += chunk));
+    const completion = new Promise((resolve) => {
+        child.once("error", (error) => {
+            spawnError = error;
+        });
+        child.once("close", (code) => {
+            closed = true;
+            resolve(code);
+        });
+    });
+    const lines = createInterface({
+        input: child.stdout,
+        crlfDelay: Number.POSITIVE_INFINITY,
+    });
+    try {
+        for await (const line of lines) {
+            if (line.trim() === "")
+                continue;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch (error) {
+                throw new Error(`${label}: invalid JSON: ${String(error)}`);
+            }
+            yield parseContract(schema, value, label);
+        }
+        const code = await completion;
+        if (spawnError)
+            throw spawnError;
+        if (code !== 0) {
+            const error = processError(code, stderr);
+            if (historyStream && historyNotFound(error))
+                throw asHistoryNotFound(error);
+            throw error;
+        }
+    }
+    finally {
+        lines.close();
+        child.stdout.destroy();
+        if (!closed) {
+            child.kill();
+            await completion;
+        }
+    }
+}
 function pushMany(args, flag, values) {
     for (const value of values ?? [])
         args.push(flag, value);
 }
+function runArguments(input, stream) {
+    const args = ["run", "--prompt", input.prompt, "--compact"];
+    pushMany(args, "--harness", input.harnesses);
+    pushMany(args, "--model", input.models);
+    if (input.system !== undefined)
+        args.push("--system", input.system);
+    if (input.reasoning !== undefined)
+        args.push("--reasoning", input.reasoning);
+    if (input.resume !== undefined)
+        args.push("--resume", input.resume);
+    if (input.session !== undefined)
+        args.push("--session", input.session);
+    if (input.fork)
+        args.push("--fork");
+    if (input.mode)
+        args.push("--mode", input.mode);
+    if (input.timeoutSeconds !== undefined)
+        args.push("--timeout", String(input.timeoutSeconds));
+    if (input.events)
+        args.push("--events");
+    if (stream)
+        args.push("--stream");
+    if (input.history)
+        args.push("--history");
+    if (input.historyName !== undefined)
+        args.push("--history-name", input.historyName);
+    if (input.historyDir !== undefined)
+        args.push("--history-dir", input.historyDir);
+    for (const [key, value] of Object.entries(input.historyLabels ?? {}))
+        args.push("--history-label", `${key}=${value}`);
+    for (const [key, value] of Object.entries(input.env ?? {}))
+        args.push("--env", `${key}=${value}`);
+    for (const [key, value] of Object.entries(input.bins ?? {}))
+        args.push("--bin", `${key}=${value}`);
+    return args;
+}
 export class OneHarness {
     options;
     constructor(options = {}) {
@@ -67,38 +190,14 @@ export class OneHarness {
     }
     async run(options) {
         const input = parseContract(RunOptionsSchema, options, "invalid oneharness run options");
-        const args = ["run", "--prompt", input.prompt, "--compact"];
-        pushMany(args, "--harness", input.harnesses);
-        pushMany(args, "--model", input.models);
-        if (input.system !== undefined)
-            args.push("--system", input.system);
-        if (input.reasoning !== undefined)
-            args.push("--reasoning", input.reasoning);
-        if (input.resume !== undefined)
-            args.push("--resume", input.resume);
-        if (input.session !== undefined)
-            args.push("--session", input.session);
-        if (input.fork)
-            args.push("--fork");
-        if (input.mode)
-            args.push("--mode", input.mode);
-        if (input.timeoutSeconds !== undefined)
-            args.push("--timeout", String(input.timeoutSeconds));
-        if (input.events)
-            args.push("--events");
-        if (input.history)
-            args.push("--history");
-        if (input.historyName !== undefined)
-            args.push("--history-name", input.historyName);
-        if (input.historyDir !== undefined)
-            args.push("--history-dir", input.historyDir);
-        for (const [key, value] of Object.entries(input.env ?? {}))
-            args.push("--env", `${key}=${value}`);
-        for (const [key, value] of Object.entries(input.bins ?? {}))
-            args.push("--bin", `${key}=${value}`);
+        const args = runArguments(input, false);
         const value = await invokeWith(this.options, args, input.cwd, true);
         return parseContract(RunReportSchema, value, "invalid oneharness run contract");
     }
+    runStream(options) {
+        const input = parseContract(RunOptionsSchema, options, "invalid oneharness run options");
+        return invokeStreamWith(this.options, runArguments(input, true), RunStreamEnvelopeSchema, "invalid oneharness run stream contract", input.cwd);
+    }
     async list() {
         const value = await invokeWith(this.options, ["list", "--compact"]);
         return parseContract(ListReportSchema, value, "invalid oneharness list contract").harnesses;
@@ -128,7 +227,15 @@ export class OneHarness {
             args.push("--all-projects");
         if (input.historyDir)
             args.push("--history-dir", input.historyDir);
-        const value = await invokeWith(this.options, args);
+        let value;
+        try {
+            value = await invokeWith(this.options, args);
+        }
+        catch (error) {
+            if (historyNotFound(error))
+                throw asHistoryNotFound(error);
+            throw error;
+        }
         return parseContract(HistoryRecordsSchema, value, "invalid history contract");
     }
     async historyList(options = {}) {
@@ -143,4 +250,19 @@ export class OneHarness {
         const value = await invokeWith(this.options, args);
         return parseContract(HistoryListSchema, value, "invalid history list contract");
     }
+    historyWatch(options = {}) {
+        const input = parseContract(HistoryWatchOptionsSchema, options, "invalid oneharness history watch options");
+        const args = ["history", "watch", "--format", "jsonl"];
+        if (input.after)
+            args.push("--after", input.after);
+        for (const [key, value] of Object.entries(input.labels ?? {}))
+            args.push("--label", `${key}=${value}`);
+        if (input.project)
+            args.push("--project", input.project);
+        if (input.allProjects)
+            args.push("--all-projects");
+        if (input.historyDir)
+            args.push("--history-dir", input.historyDir);
+        return invokeStreamWith(this.options, args, HistoryStreamEnvelopeSchema, "invalid oneharness history watch contract", undefined, true);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneharness/sdk",
-  "version": "0.3.23",
+  "version": "0.4.0",
   "description": "Typed Node.js SDK for oneharness",
   "type": "module",
   "main": "dist/index.js",
@@ -19,7 +19,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "oneharness-cli": "0.3.23",
+    "oneharness-cli": "0.4.0",
     "zod": "^4.4.3"
   }
 }