@chipschat/harness 0.0.0-stage → 1.0.1

package/dist/lane.js

@@ -0,0 +1,105 @@
+/**
+ * A lane, from the lead's side: what `run.task()` hands back. The task is acknowledged with
+ * where the lane lives and which run it is; from then on the lead hears the lane's news as
+ * `lane.updated` — waiting, completed with the specialist's summary and what it cost, failed,
+ * cancelled — and `result` resolves with the last of those. A task Chips flattened into a step
+ * has no lane, and `result` says so at once.
+ *
+ * A lane between two spaces of one harness — a Space handed down to, a subagent — is routed to
+ * the harness itself, and the lead works it: `work()` is the run to post into (M3.5, ADR 0032).
+ */
+import { Emitter } from "./events.js";
+const OVER = new Set(["completed", "failed", "cancelled"]);
+export class Lane {
+    id;
+    wire;
+    events = new Emitter();
+    settle;
+    stop;
+    laneState = "opening";
+    laneRunId;
+    laneSpaceId;
+    lastSummary;
+    lastCost;
+    /** Resolves when the lane ends, or at once when the task was flattened. Never rejects. */
+    result;
+    constructor(id, wire) {
+        this.id = id;
+        this.wire = wire;
+        this.result = new Promise((resolve) => {
+            this.settle = resolve;
+        });
+        // Listening before the task is sent: the specialist may answer before the ack arrives.
+        this.stop = wire.hear(id, (event) => this.onUpdated(event));
+    }
+    /** The specialist's run, which the lane is. Known once the task is acknowledged. */
+    get runId() {
+        return this.laneRunId;
+    }
+    /** Where the lane lives. Known once the task is acknowledged. */
+    get spaceId() {
+        return this.laneSpaceId;
+    }
+    /** Where the lane got to: `opening` until acknowledged, then the specialist's state. */
+    get state() {
+        return this.laneState;
+    }
+    get summary() {
+        return this.lastSummary;
+    }
+    get costUsd() {
+        return this.lastCost;
+    }
+    /** True once the lane will not change again. */
+    get over() {
+        return this.laneState === "flattened" || OVER.has(this.laneState);
+    }
+    on(name, handler) {
+        return this.events.on(name, handler);
+    }
+    /**
+     * The lane's run, for a lead that works the lane itself — a lane between two of its own
+     * spaces. Everything sent on it lands in the lane's home, as the lane's own steps and messages.
+     */
+    work() {
+        if (this.laneRunId === undefined || this.laneSpaceId === undefined) {
+            throw new Error(this.laneState === "flattened"
+                ? "this task was flattened into a step; there is no lane to work"
+                : "the lane has not been acknowledged yet");
+        }
+        return this.wire.accept(this.laneRunId, this.laneSpaceId, this.id);
+    }
+    /** The task's acknowledgement: where the lane is, or that there is none. */
+    opened(lane) {
+        if (lane === undefined) {
+            this.laneState = "flattened";
+            this.finish({ state: "flattened" });
+            return;
+        }
+        this.laneRunId = lane.runId;
+        this.laneSpaceId = lane.spaceId;
+        if (this.laneState === "opening")
+            this.laneState = "running";
+    }
+    onUpdated(event) {
+        this.laneState = event.state;
+        this.lastSummary = event.summary ?? this.lastSummary;
+        this.lastCost = event.cost_usd ?? this.lastCost;
+        this.events.emit("updated", event);
+        if (event.state === "completed" || event.state === "failed" || event.state === "cancelled") {
+            this.finish({
+                state: event.state,
+                summary: this.lastSummary,
+                costUsd: this.lastCost,
+                event,
+            });
+        }
+    }
+    finish(outcome) {
+        this.stop?.();
+        this.stop = undefined;
+        this.settle?.(outcome);
+        this.settle = undefined;
+    }
+}
+//# sourceMappingURL=lane.js.map

package/dist/lane.js.map

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

package/dist/outbox.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What has been sent and not yet answered. A socket comes and goes; a harness's events must
+ * not. Every event carries an idempotency key and the server answers each with an `ack` or an
+ * `error` naming it; until then the event waits here, and every socket that opens — the first
+ * time, or again after a drop — sends the unanswered ones first. A resend the server had
+ * already applied comes back `duplicate: true`, which is what the key is for.
+ */
+export interface Ack {
+    readonly idempotencyKey: string;
+    readonly seq: number;
+    readonly duplicate: boolean;
+    /** For a `task` that opened a lane: where it lives and which run it is (M3.5). */
+    readonly lane?: {
+        readonly laneId: string;
+        readonly runId: string;
+        readonly spaceId: string;
+    };
+    /**
+     * A message Chips took into the room but held from the agents it named (ADR 0097): they have
+     * sent each other their allowance since a person last acted, or a person paused them. Tell the
+     * model, so it says what is done and what is blocked rather than waiting on them.
+     */
+    readonly held?: true;
+    /**
+     * With `held`: the messages between agents since the reset, and the workspace's hold (ADR
+     * 0187), absent where it holds them only on a pause.
+     */
+    readonly exchange?: {
+        readonly count: number;
+        readonly allowance?: number;
+    };
+}
+export declare class RefusedError extends Error {
+    readonly code: string;
+    readonly idempotencyKey?: string | undefined;
+    readonly name = "RefusedError";
+    constructor(code: string, message: string, idempotencyKey?: string | undefined);
+}
+export interface Outbox {
+    /** Hold an event until the server answers for its key. */
+    readonly add: (key: string, event: Readonly<Record<string, unknown>>) => Promise<Ack>;
+    readonly unanswered: () => readonly Readonly<Record<string, unknown>>[];
+    readonly acked: (ack: Ack) => void;
+    readonly refused: (error: RefusedError) => void;
+    /** Reject everything still waiting: the connection is gone for good. */
+    readonly abandon: (reason: string) => void;
+    readonly size: () => number;
+}
+export declare function createOutbox(): Outbox;
+//# sourceMappingURL=outbox.d.ts.map

package/dist/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../src/outbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9F;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E;AAED,qBAAa,YAAa,SAAQ,KAAK;IAGnC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM;IAJlC,SAAkB,IAAI,kBAAkB;gBAE7B,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,cAAc,CAAC,EAAE,MAAM,YAAA;CAInC;AAQD,MAAM,WAAW,MAAM;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IACxE,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAChD,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,wBAAgB,YAAY,IAAI,MAAM,CA8BrC"}

package/dist/outbox.js

@@ -0,0 +1,52 @@
+/**
+ * What has been sent and not yet answered. A socket comes and goes; a harness's events must
+ * not. Every event carries an idempotency key and the server answers each with an `ack` or an
+ * `error` naming it; until then the event waits here, and every socket that opens — the first
+ * time, or again after a drop — sends the unanswered ones first. A resend the server had
+ * already applied comes back `duplicate: true`, which is what the key is for.
+ */
+export class RefusedError extends Error {
+    code;
+    idempotencyKey;
+    name = "RefusedError";
+    constructor(code, message, idempotencyKey) {
+        super(message);
+        this.code = code;
+        this.idempotencyKey = idempotencyKey;
+    }
+}
+export function createOutbox() {
+    const waiting = new Map();
+    return {
+        add(key, event) {
+            return new Promise((resolve, reject) => {
+                waiting.set(key, { event, resolve, reject });
+            });
+        },
+        unanswered: () => [...waiting.values()].map((entry) => entry.event),
+        acked(ack) {
+            const entry = waiting.get(ack.idempotencyKey);
+            if (entry === undefined)
+                return;
+            waiting.delete(ack.idempotencyKey);
+            entry.resolve(ack);
+        },
+        refused(error) {
+            if (error.idempotencyKey === undefined)
+                return;
+            const entry = waiting.get(error.idempotencyKey);
+            if (entry === undefined)
+                return;
+            waiting.delete(error.idempotencyKey);
+            entry.reject(error);
+        },
+        abandon(reason) {
+            for (const [key, entry] of waiting) {
+                waiting.delete(key);
+                entry.reject(new RefusedError("closed", reason, key));
+            }
+        },
+        size: () => waiting.size,
+    };
+}
+//# sourceMappingURL=outbox.js.map

package/dist/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../src/outbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAG1B;IAEA;IAJO,IAAI,GAAG,cAAc,CAAC;IACxC,YACW,IAAY,EACrB,OAAe,EACN,cAAuB;QAEhC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,SAAI,GAAJ,IAAI,CAAQ;QAEZ,mBAAc,GAAd,cAAc,CAAS;IAGlC,CAAC;CACF;AAmBD,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC3C,OAAO;QACL,GAAG,CAAC,GAAG,EAAE,KAAK;YACZ,OAAO,IAAI,OAAO,CAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC1C,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC;QACL,CAAC;QACD,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;QACnE,KAAK,CAAC,GAAG;YACP,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YAC9C,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO;YAChC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YACnC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,KAAK;YACX,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS;gBAAE,OAAO;YAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;YAChD,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO;YAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;YACrC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,CAAC,MAAM;YACZ,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;gBACnC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACpB,KAAK,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QACD,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI;KACzB,CAAC;AACJ,CAAC"}

package/dist/project.d.ts

@@ -0,0 +1,224 @@
+/**
+ * A room's project, for one agent (ADR 0221): the agent works in a copy of its own, `<its
+ * folder>/room`, and the bridge does the git, never the agent.
+ *
+ * - **Before a turn, `pull`.** The copy is made on first use, its leave-out list written into its
+ *   own `info/exclude`, and brought up to date with the room's `main`. What a turn left unsent goes
+ *   in first, so nothing of it is lost. What others changed since the agent's last turn, and who, is
+ *   what the turn is told, with a clash still to settle or a key to take out (`renderProjectNote`).
+ * - **After a turn, `push`.** Everything the agent changed is committed under its name, with the
+ *   first line of its words for the subject, and sent. When somebody sent first, the agent's commits
+ *   are replayed on top of theirs and sent again. When the two changes overlap, the replay stops and
+ *   the two are merged instead, so that both sides are marked in the agent's copy, labelled `yours`
+ *   and with whose they clashed with; nothing is sent until the agent has settled them.
+ * - **What is never committed.** The leave-out list, and a file whose words look like a key: then
+ *   nothing of the change is committed, and the next turn is told which file and why. The server
+ *   refuses the same (ADR 0220), as the backstop.
+ *
+ * The token never reaches git's command line or a file: it goes through `GIT_CONFIG_*` in git's
+ * environment, beside the agent in `chips-actor`, so an agent's own `git push` carries neither.
+ * That keeps the token out of the copy, not out of the agent's reach: the agent can write the
+ * copy's `.git/config`, which git reads on every run. So the bridge fetches and sends by the
+ * project's URL, never what `origin` names, turns `core.fsmonitor` off, and leaves an agent's copy
+ * alone while its config holds anything git and the bridge didn't put there, such as a rewritten
+ * URL, a proxy or a program for git to run (SEC-52). git reads none of the machine's config and
+ * runs none of its hooks, so a person's own git setup (a signing key, a hook, `pull.rebase`) changes
+ * nothing here.
+ *
+ * **A person's folder** is the same copy with `person` set (ADR 0224), as the Mac app's Your folder
+ * keeps it: the folder itself is the copy, the token a project token and the commits theirs. It is
+ * never committed to behind their back: `look` brings it up to `main` only while nothing in it is
+ * theirs, and `push` sends what they changed when they say Send.
+ */
+import { type ProjectFacts } from "@chipschat/protocol";
+export interface ProjectOptions {
+    /** Where chipsd is: `http://127.0.0.1:4431`. */
+    readonly url: string;
+    /** The harness's token. */
+    readonly token: string;
+    readonly spaceId: string;
+    /** The agent the turns are for: what `chips-actor` names, and the commits' author. */
+    readonly agentId: string;
+    /** The agent's name, as its commits are signed. */
+    readonly name: string;
+    /** The agent's own folder; its copy of the project is `room` in it. */
+    readonly folder: string;
+    /** The git to run. `git` on the `PATH` unless said. */
+    readonly git?: string | undefined;
+    /** The `PATH` git is run with. This process's unless said. */
+    readonly path?: string | undefined;
+    /** Told what went wrong, for the bridge's log. */
+    readonly log?: ((line: string) => void) | undefined;
+    /**
+     * A person's own folder rather than an agent's copy (ADR 0224): `token` is a project token, sent
+     * with no `chips-actor`; `agentId` is the person's id, their commits `<id>@people.chips.invalid`;
+     * and the copy is `folder` itself.
+     */
+    readonly person?: boolean | undefined;
+}
+/** A file a person changed in their folder and hasn't sent, with the lines it adds and takes out. */
+export interface FolderChange {
+    readonly path: string;
+    readonly added: number;
+    readonly removed: number;
+}
+/** A person's folder as it stands (ADR 0224), for Your folder's card. */
+export interface FolderLook {
+    /** What they changed and haven't sent: none while it is the room's `main`. */
+    readonly changed: readonly FolderChange[];
+    /** Files with both sides of a clash marked in them, and whose change they clashed with. */
+    readonly clashes: readonly string[];
+    readonly clashedWith: readonly string[];
+    /** The first marked lines of the first of them, with a line before and after. */
+    readonly marked?: string | undefined;
+    /** What others changed that isn't in the folder yet, because the person has changes of their own. */
+    readonly since: readonly string[];
+    readonly by: readonly string[];
+    /** What came in from the room this time, and whose it was. */
+    readonly came: readonly string[];
+    readonly cameBy: readonly string[];
+    /** Why the room's project couldn't be reached, in git's or the server's words. */
+    readonly trouble?: string | undefined;
+}
+/** What `push` did with the turn's work. */
+export type Pushed = {
+    readonly state: "sent";
+    /** Where the room's `main` is now: this push's commit. */
+    readonly commit: string;
+    readonly files: readonly string[];
+    /** Whose changes it was replayed on top of, by name; none when it went straight on. */
+    readonly over: readonly string[];
+}
+/** Nothing changed in the copy. */
+ | {
+    readonly state: "nothing";
+}
+/** It clashed with somebody's change, and both sides are marked in the copy for the next turn. */
+ | {
+    readonly state: "clash";
+    readonly files: readonly string[];
+    readonly with: readonly string[];
+}
+/** A file in it looks like it holds a key, so nothing was committed. */
+ | {
+    readonly state: "keys";
+    readonly keys: readonly {
+        path: string;
+        what: string;
+    }[];
+}
+/** The room's project turned it back, in the server's words. */
+ | {
+    readonly state: "refused";
+    readonly why: string;
+}
+/** It couldn't be sent: the server unreachable, or others sending first again and again. */
+ | {
+    readonly state: "failed";
+    readonly why: string;
+};
+/** A commit's subject: the first line of the agent's words, as it said it. */
+export declare function subjectOf(words: string): string;
+/** What `push` did, in a few words for the bridge's log. */
+export declare function pushedInWords(pushed: Pushed): string;
+/**
+ * What a reply says after its words when its change didn't reach the room's project (AP-6, ADR
+ * 0222's addendum): a line in brackets, as a file that didn't attach has (`sendAnswer`), so that
+ * "it's in the project" is never the last word on a change that isn't. Nothing when it was sent,
+ * or when nothing changed.
+ */
+export declare function heldNote(pushed: Pushed, name: string): string | undefined;
+/** Whether this machine has a git new enough for a room's project, or why not. */
+export declare function checkGit(git?: string, path?: string): Promise<{
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    why: string;
+}>;
+export declare class Project {
+    private readonly options;
+    /** The agent's copy of the project. */
+    readonly copy: string;
+    private readonly remote;
+    constructor(options: ProjectOptions);
+    /** Before a turn: the copy made or brought up to date, and what the turn is to be told of it. */
+    pull(): Promise<ProjectFacts>;
+    /** After a turn: what the agent changed, committed under its name and sent to the room. */
+    push(input: {
+        readonly words: string;
+    }): Promise<Pushed>;
+    /**
+     * A person's folder made, or brought up to the room's `main` while nothing in it is theirs: no
+     * file changed or added, nothing waiting to be sent, no clash (ADR 0224). Once something is
+     * theirs, nothing in the folder changes; what others changed since is told instead.
+     */
+    look(): Promise<FolderLook>;
+    /** The folder moved on to the room's `main` while nothing in it is theirs: what came in, whose. */
+    private bringUntouched;
+    /**
+     * A clash the person settled by taking the room's side whole: nothing of theirs is left to send,
+     * so the folder goes back to the room's `main` and is kept up to date again. Every tracked file
+     * is already the room's, and a file git doesn't track is never touched.
+     */
+    private settledAsTheirs;
+    /** Whether nothing in the folder is the person's own: no change, no unsent commit, no clash. */
+    private untouched;
+    /** What the person changed, a clash, and what others changed that the folder hasn't. */
+    private standing;
+    /**
+     * What the person's changes are measured from: where the folder and the room's `main` parted.
+     * In a clash the room's side is already in the folder, so it is `main` itself: what differs from
+     * it is what Send would change.
+     */
+    private baseOf;
+    /** How many lines a file the person added has: the lines it adds. None for a picture. */
+    private lineCount;
+    /** The first clash in a file, from the line before its first mark to the line after its last. */
+    private markedLines;
+    /**
+     * One try at sending: sent, nothing to send, or turned back; or, when somebody sent first, the
+     * agent's commits replayed on top of theirs, for the next try, unless they clashed.
+     */
+    private send;
+    /** The room's branches, from the project's own URL rather than whatever `origin` names (SEC-52). */
+    private fetch;
+    /**
+     * Why an agent's copy is left alone: its config holds a setting git and the bridge didn't write,
+     * or can't be read (SEC-52). Nothing for a person's folder, whose config is theirs.
+     */
+    private foreignConfig;
+    /**
+     * The copy, made on first use, pointed at the room's project, its leave-out list written: whether
+     * it was made now.
+     */
+    private ready;
+    /** The copy at the room's `main`, with the agent's own unsent commits replayed on top. */
+    private bringUp;
+    /**
+     * The agent's commits replayed on top of `onto`. Where they overlap, the replay is undone and the
+     * two merged instead, which leaves both sides marked in the files, labelled for whose they are.
+     * Two copies that both began in an empty project share no commit, and the merge is still made.
+     */
+    private replay;
+    /** git's labels for a clash's two sides, `HEAD` and a commit, as a person reads them. */
+    private label;
+    /** Files git still holds as clashing that still carry marks. */
+    private marked;
+    /** Whose change a clash in progress is with, by name. */
+    private mergingWith;
+    /**
+     * Everything in the copy committed as the agent, a clash it settled included; nothing when
+     * nothing changed. A file that looks like it holds a key stops the commit: the keys, by file.
+     */
+    private commit;
+    /** Which of these files hold what looks like a key, and whose. */
+    private keysIn;
+    private facts;
+    /** Who made the commits in a range, by name, the agent itself left out. */
+    private authors;
+    private head;
+    private emptyTree;
+    private git;
+}
+//# sourceMappingURL=project.d.ts.map

package/dist/project.d.ts.map

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