@chipschat/harness 0.0.0-stage → 1.0.0

package/dist/settings.js

@@ -0,0 +1,228 @@
+/**
+ * What a person changes about an agent from its page, kept by the harness (ADRs 0134, 0140, 0143,
+ * 0146): its context files, its model and effort, its heartbeat, its context window; and the jobs
+ * the harness runs on its own, from the harness's page (ADR 0252). One pattern five times. The harness sends its copy (`put…`) when it connects and whenever it changes on its
+ * own side; a person's change arrives as a frame, now or never; the harness makes it in its own way
+ * and answers with the copy as it is now. Here a handler does the making and returns the copy, and
+ * the answer — `answers`, or `refuses` when the handler throws — is sent for it.
+ */
+import { contextEditFrame, heartbeatChangeFrame, JOB_RUNS_POST_MAX, jobChangeFrame, modelChangeFrame, windowChangeFrame, windowCompactFrame, } from "@chipschat/protocol";
+/**
+ * A change the harness won't or can't make. Throw it from a handler with the copy as it is now:
+ * the person is told `message`, and sees the copy. Anything else thrown refuses the same way, with
+ * the copy last sent for that agent, and its message.
+ */
+export class Refuse extends Error {
+    copy;
+    reason;
+    name = "Refuse";
+    constructor(message, 
+    /** The copy as it is now. Absent: the one last sent for that agent. */
+    copy, 
+    /** For a context file only: `changed` when the file moved on since the person's version. */
+    reason) {
+        super(message);
+        this.copy = copy;
+        this.reason = reason;
+    }
+}
+/** What `hello.accepts` says for these handlers, beside `restart` for a restart handler. */
+export function acceptsFor(handlers) {
+    if (handlers === undefined)
+        return [];
+    return [
+        ...(handlers.context === undefined ? [] : ["context"]),
+        ...(handlers.models === undefined ? [] : ["models"]),
+        ...(handlers.heartbeats === undefined ? [] : ["heartbeats"]),
+        ...(handlers.contextWindows === undefined ? [] : ["context_windows"]),
+        ...(handlers.jobs === undefined ? [] : ["jobs"]),
+    ];
+}
+const PATHS = {
+    context: (id) => `/v1/agents/${encodeURIComponent(id)}/context`,
+    "harness-context": (id) => `/v1/harnesses/${encodeURIComponent(id)}/context`,
+    model: (id) => `/v1/agents/${encodeURIComponent(id)}/model`,
+    heartbeat: (id) => `/v1/agents/${encodeURIComponent(id)}/heartbeat`,
+    "context-window": (id) => `/v1/agents/${encodeURIComponent(id)}/context-window`,
+    jobs: (id) => `/v1/harnesses/${encodeURIComponent(id)}/jobs`,
+};
+/** The frames heard here, each by the schema it is read by (SEC-14). */
+const FRAMES = {
+    "context.edit": contextEditFrame,
+    "model.change": modelChangeFrame,
+    "heartbeat.change": heartbeatChangeFrame,
+    "context_window.compact": windowCompactFrame,
+    "context_window.change": windowChangeFrame,
+    "job.change": jobChangeFrame,
+};
+/**
+ * The harness's copies, sent and remembered: `chips.settings`. Each `put` sends the whole copy;
+ * the last one sent for each agent is what a refusal carries when a handler gives none. A copy
+ * the same as the last one Chips took for that agent is not sent again, unless it answers a
+ * person, so a harness may send its copies as often as it reads them; and one agent's copies of
+ * a kind go one after another, so a later one never lands before an earlier one.
+ */
+export class Settings {
+    put;
+    harnessId;
+    handlers;
+    post;
+    /** The copy last given for each `kind:id`, for a refusal to carry. */
+    sent = new Map();
+    /** The copy Chips last took for each `kind:id`, as JSON. */
+    landed = new Map();
+    chains = new Map();
+    constructor(put, harnessId, handlers, 
+    /** A `POST` to chipsd with the harness's token, for its jobs' runs. */
+    post) {
+        this.put = put;
+        this.harnessId = harnessId;
+        this.handlers = handlers;
+        this.post = post;
+    }
+    /** An agent's context files (`context_files`). */
+    context(agentId, copy) {
+        return this.send("context", agentId, copy, {});
+    }
+    /** The harness's own shared set, which its agents read or start from (`context_files`). */
+    harnessContext(copy) {
+        return this.send("harness-context", this.harnessId(), copy, {});
+    }
+    /** An agent's model and effort, what it may run on instead, and the words for each (`models`). */
+    model(agentId, copy) {
+        return this.send("model", agentId, copy, {});
+    }
+    /** An agent's heartbeat (`heartbeats`). */
+    heartbeat(agentId, copy) {
+        return this.send("heartbeat", agentId, copy, {});
+    }
+    /** An agent's context window: how full, its limit, its last compaction (`context_windows`). */
+    contextWindow(agentId, copy) {
+        return this.send("context-window", agentId, copy, {});
+    }
+    /** The jobs the harness runs on its own, all of them (`jobs`). */
+    jobs(copy) {
+        return this.send("jobs", this.harnessId(), copy, {});
+    }
+    /**
+     * Runs of its jobs the harness finished (`jobs`), two hundred to a post. A run sent again says
+     * what it says over the one before, and what it leaves out stays, so send it once more when its
+     * cost is known, and again without one does no harm. Send the copy first:
+     * Chips refuses runs of a job its copy doesn't list.
+     */
+    async jobRuns(runs) {
+        if (this.post === undefined)
+            throw new Error("This connection can't post a job's runs.");
+        const path = `${PATHS.jobs(this.harnessId())}/runs`;
+        for (let at = 0; at < runs.length; at += JOB_RUNS_POST_MAX) {
+            await this.post(path, { runs: runs.slice(at, at + JOB_RUNS_POST_MAX) });
+        }
+    }
+    /** An agent deleted: nothing is remembered of it, so a copy for an agent made again is sent. */
+    forget(agentId) {
+        for (const kind of Object.keys(PATHS)) {
+            const key = `${kind}:${agentId}`;
+            this.sent.delete(key);
+            this.landed.delete(key);
+            this.chains.delete(key);
+        }
+    }
+    /**
+     * A compaction taken (its handler returned) that then failed: the ask refused after all, with
+     * the harness's words, beside the copy as it is now, or the one last sent.
+     */
+    contextWindowFailed(agentId, changeId, message, copy) {
+        const now = copy ?? this.sent.get(`context-window:${agentId}`);
+        if (now === undefined)
+            return Promise.resolve(undefined);
+        const words = message.slice(0, 300);
+        return this.send("context-window", agentId, now, {
+            refuses: { change_id: changeId, ...(words === "" ? {} : { message: words }) },
+        });
+    }
+    /**
+     * A frame from Chips, if it is one of these: read by its schema (SEC-14), handed to its handler
+     * and answered. The answer's promise, which never rejects; nothing for any other frame, and
+     * nothing for a frame that is not what it says it is.
+     */
+    hear(frame) {
+        const name = frame["frame"];
+        const schema = typeof name === "string" && name in FRAMES ? FRAMES[name] : undefined;
+        if (schema === undefined)
+            return undefined;
+        // Read by its schema, not cast (SEC-14): what is acted on here is written to disk by the
+        // harness — a context file under the agent's folder, by the name the frame gives — so a frame
+        // that is not what it says it is, a name that climbs out of the folder among them, reaches no
+        // handler. Chips never sends one; the person is told the edit was missed after a minute.
+        const parsed = schema.safeParse(frame);
+        return parsed.success ? this.heard(parsed.data) : undefined;
+    }
+    /** One of the frames read, handed to its handler and answered. */
+    heard(frame) {
+        const handlers = this.handlers;
+        switch (frame.frame) {
+            case "context.edit": {
+                const kind = frame.agent_id === undefined ? "harness-context" : "context";
+                return this.answer(kind, frame.agent_id ?? this.harnessId(), frame.edit_id, "edit_id", () => handlers?.context?.(frame));
+            }
+            case "model.change":
+                return this.answer("model", frame.agent_id, frame.change_id, "change_id", () => handlers?.models?.(frame));
+            case "heartbeat.change":
+                return this.answer("heartbeat", frame.agent_id, frame.change_id, "change_id", () => handlers?.heartbeats?.(frame));
+            case "job.change":
+                return this.answer("jobs", this.harnessId(), frame.change_id, "change_id", () => handlers?.jobs?.(frame));
+            case "context_window.compact":
+                return this.answer("context-window", frame.agent_id, frame.change_id, "change_id", () => handlers?.contextWindows?.compact(frame));
+            default:
+                return this.answer("context-window", frame.agent_id, frame.change_id, "change_id", () => handlers?.contextWindows?.change(frame));
+        }
+    }
+    send(kind, id, copy, answer) {
+        const key = `${kind}:${id}`;
+        this.sent.set(key, copy);
+        const print = JSON.stringify(copy);
+        const answering = Object.keys(answer).length > 0;
+        const next = (this.chains.get(key) ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(async () => {
+            if (!answering && this.landed.get(key) === print)
+                return undefined;
+            const taken = await this.put(PATHS[kind](id), { ...copy, ...answer });
+            this.landed.set(key, print);
+            return taken;
+        });
+        this.chains.set(key, next);
+        return next;
+    }
+    /**
+     * Make the change with its handler and answer with the copy: `answers` when it returns,
+     * `refuses` when it throws. With no handler and no copy ever sent there is nothing to answer
+     * with, and the person is told it was missed after a minute.
+     */
+    async answer(kind, id, askId, idField, make) {
+        try {
+            const made = make();
+            if (made === undefined)
+                throw new Refuse("This harness doesn't take that change.");
+            await this.send(kind, id, await made, { answers: askId });
+        }
+        catch (error) {
+            const copy = (error instanceof Refuse ? error.copy : undefined) ?? this.sent.get(`${kind}:${id}`);
+            if (copy === undefined)
+                return;
+            const refuses = { [idField]: askId, ...refusalOf(kind, error) };
+            await this.send(kind, id, copy, { refuses }).catch(() => undefined);
+        }
+    }
+}
+/** What a refusal says beside its id: the harness's words, and for a file whether it moved on. */
+function refusalOf(kind, error) {
+    const message = (error instanceof Error ? error.message : String(error)).slice(0, 300);
+    const file = kind === "context" || kind === "harness-context";
+    const reason = error instanceof Refuse ? error.reason : undefined;
+    return {
+        ...(file ? { reason: reason ?? "failed" } : {}),
+        ...(message === "" ? {} : { message }),
+    };
+}
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

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

package/dist/steps.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A bridge's steps, said to the `chips connect` that started it (ADR 0218). `chips connect` sets
+ * `CHIPS_STEPS=json` and reads standard output for lines that open with `chips-step `: `joining`
+ * when `join()` starts, `keeping` when keep starts the service. A bridge says its own check of its
+ * harness, `checking` and `checked`, with a few words of its own under it (`detail`), and where it
+ * stopped, `failed`, with its words for a sheet (`StopWords`), which Chips for Mac shows (phase 5).
+ * Everything else a bridge writes is its own, and passed on as it is. With nothing set, nothing is
+ * written.
+ */
+import type { Environment } from "./keep.js";
+/** What opens a step's line: the rest of it is JSON. */
+export declare const STEP_MARK = "chips-step ";
+export type StepName = "checking" | "checked" | "joining" | "keeping" | "failed";
+/**
+ * Where a bridge stopped, for a sheet: a few words under the step ("Nothing answers on port
+ * 8642"), its sentence ("Its API server is off."), what to do, and a line to copy. Its full
+ * sentence still goes to standard error, for a terminal.
+ */
+export interface StopWords {
+    readonly detail?: string;
+    readonly says?: string;
+    readonly doing?: string;
+    readonly copy?: string;
+}
+/** The step on standard output, as a line, when `chips connect` asked for them. */
+export declare function reportStep(step: StepName, detail?: Readonly<Record<string, string>> | StopWords, env?: Environment, write?: (line: string) => void): void;
+//# sourceMappingURL=steps.d.ts.map

package/dist/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,wDAAwD;AACxD,eAAO,MAAM,SAAS,gBAAgB,CAAC;AAEvC,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjF;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CACxB,IAAI,EAAE,QAAQ,EACd,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAc,EAEzD,GAAG,GAAE,WAAyB,EAC9B,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAwC,GAChE,IAAI,CAON"}

package/dist/steps.js

@@ -0,0 +1,26 @@
+/**
+ * A bridge's steps, said to the `chips connect` that started it (ADR 0218). `chips connect` sets
+ * `CHIPS_STEPS=json` and reads standard output for lines that open with `chips-step `: `joining`
+ * when `join()` starts, `keeping` when keep starts the service. A bridge says its own check of its
+ * harness, `checking` and `checked`, with a few words of its own under it (`detail`), and where it
+ * stopped, `failed`, with its words for a sheet (`StopWords`), which Chips for Mac shows (phase 5).
+ * Everything else a bridge writes is its own, and passed on as it is. With nothing set, nothing is
+ * written.
+ */
+import { writeSync } from "node:fs";
+/** What opens a step's line: the rest of it is JSON. */
+export const STEP_MARK = "chips-step ";
+/** The step on standard output, as a line, when `chips connect` asked for them. */
+export function reportStep(step, detail = {}, 
+// biome-ignore lint/style/noProcessEnv: `chips connect` asks for the steps in the environment.
+env = process.env, write = (line) => void writeSync(1, line)) {
+    if (env["CHIPS_STEPS"] !== "json")
+        return;
+    try {
+        write(`${STEP_MARK}${JSON.stringify({ step, ...detail })}\n`);
+    }
+    catch {
+        // Nobody is reading: the step was for them alone.
+    }
+}
+//# sourceMappingURL=steps.js.map

package/dist/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGpC,wDAAwD;AACxD,MAAM,CAAC,MAAM,SAAS,GAAG,aAAa,CAAC;AAgBvC,mFAAmF;AACnF,MAAM,UAAU,UAAU,CACxB,IAAc,EACd,SAAuD,EAAE;AACzD,+FAA+F;AAC/F,MAAmB,OAAO,CAAC,GAAG,EAC9B,QAAgC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC;IAEjE,IAAI,GAAG,CAAC,aAAa,CAAC,KAAK,MAAM;QAAE,OAAO;IAC1C,IAAI,CAAC;QACH,KAAK,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;IACpD,CAAC;AACH,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What a harness keeps across a restart, so a restart loses nothing and leaves nothing hanging:
+ * the last `seq` it heard (a decision made while it was down still reaches it), the events it sent
+ * that the server never answered (sent again, which the idempotency key makes safe), and the runs
+ * it started that never ended (ended for it when it comes back, so no thinking bubble waits for
+ * ever). `connect({ store: fileStore(path) })`; without a store, all of it lives as long as the
+ * process does.
+ */
+/** A run this harness started and has not ended: enough to end it after a restart. */
+export interface OpenRun {
+    readonly runId: string;
+    readonly spaceId: string;
+    /** The agent it was started as, when it was one (ADR 0087). */
+    readonly agentId?: string | undefined;
+}
+export interface HarnessState {
+    readonly since?: number | undefined;
+    readonly outbox: readonly Readonly<Record<string, unknown>>[];
+    readonly runs: readonly OpenRun[];
+}
+/** Where the state is kept. `load` is read once, at connect; `save` is called after changes. */
+export interface HarnessStore {
+    readonly load: () => HarnessState | undefined;
+    readonly save: (state: HarnessState) => void;
+}
+/**
+ * A JSON file only its user can read, written whole and renamed into place so a crash mid-write
+ * leaves the last good one. Its folder is made when missing.
+ */
+export declare function fileStore(path: string): HarnessStore;
+/** A store in memory, for tests and for a harness that keeps its state somewhere of its own. */
+export declare function memoryStore(initial?: HarnessState): HarnessStore & {
+    readonly state: () => HarnessState | undefined;
+};
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,sFAAsF;AACtF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC9D,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CACnC;AAED,gGAAgG;AAChG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,YAAY,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAuBpD;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CACzB,OAAO,CAAC,EAAE,YAAY,GACrB,YAAY,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,YAAY,GAAG,SAAS,CAAA;CAAE,CASnE"}

package/dist/store.js

@@ -0,0 +1,52 @@
+/**
+ * What a harness keeps across a restart, so a restart loses nothing and leaves nothing hanging:
+ * the last `seq` it heard (a decision made while it was down still reaches it), the events it sent
+ * that the server never answered (sent again, which the idempotency key makes safe), and the runs
+ * it started that never ended (ended for it when it comes back, so no thinking bubble waits for
+ * ever). `connect({ store: fileStore(path) })`; without a store, all of it lives as long as the
+ * process does.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * A JSON file only its user can read, written whole and renamed into place so a crash mid-write
+ * leaves the last good one. Its folder is made when missing.
+ */
+export function fileStore(path) {
+    return {
+        load() {
+            if (!existsSync(path))
+                return undefined;
+            try {
+                const parsed = JSON.parse(readFileSync(path, "utf8"));
+                return {
+                    ...(typeof parsed.since === "number" ? { since: parsed.since } : {}),
+                    outbox: Array.isArray(parsed.outbox) ? parsed.outbox : [],
+                    runs: Array.isArray(parsed.runs) ? parsed.runs : [],
+                };
+            }
+            catch {
+                // A file nobody can read is a fresh start, not a harness that cannot start.
+                return undefined;
+            }
+        },
+        save(state) {
+            mkdirSync(dirname(path), { recursive: true });
+            const next = `${path}.next`;
+            writeFileSync(next, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+            renameSync(next, path);
+        },
+    };
+}
+/** A store in memory, for tests and for a harness that keeps its state somewhere of its own. */
+export function memoryStore(initial) {
+    let kept = initial;
+    return {
+        load: () => kept,
+        save: (state) => {
+            kept = state;
+        },
+        state: () => kept,
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO;QACL,IAAI;YACF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,OAAO,SAAS,CAAC;YACxC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAA0B,CAAC;gBAC/E,OAAO;oBACL,GAAG,CAAC,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACpE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;oBACzD,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;iBACpD,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,4EAA4E;gBAC5E,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,KAAK;YACR,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,MAAM,IAAI,GAAG,GAAG,IAAI,OAAO,CAAC;YAC5B,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACnE,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,WAAW,CACzB,OAAsB;IAEtB,IAAI,IAAI,GAAG,OAAO,CAAC;IACnB,OAAO;QACL,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI;QAChB,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;YACd,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI;KAClB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@chipschat/harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "The Agent Connect client for a harness you control: connect, start runs, log steps, ask, and hear what people say back.",
+  "license": "Apache-2.0",
+  "homepage": "https://chipschat.ai/connect/sdk/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arjungupta99/chips.git",
+    "directory": "packages/sdk-ts"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@chipschat/protocol": "1.0.0"
+  },
+  "devDependencies": {
+    "kysely": "0.29.5",
+    "vitest": "4.1.11",
+    "@chipschat/platform": "0.0.0",
+    "@chipschat/server": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "biome check ."
+  }
 }