@chipschat/protocol 0.0.0-stage → 1.0.0

package/dist/src/commands.js

@@ -0,0 +1,274 @@
+/**
+ * A command an ask carries, read the way a shell would read it (ADR 0239), so that a standing yes
+ * remembers how each part of it starts rather than the whole kind of action. Here, so the server,
+ * the conformance kit's fake and the apps read a command the same way.
+ *
+ * A command is the ask's `input.command`: a string a shell runs, or an array of words a program
+ * runs as given. A string is split into parts at `&&`, `||`, `;`, `|` and new lines outside
+ * quotes, and each part into words, quotes taken off. A command that does more than this reader
+ * can follow is not read at all: a redirection (`>`, `<`), something run inside it (`$(`,
+ * backticks, `$`, parentheses, braces), a part run in the background (`&`), a variable set before
+ * the program (`FOO=1 node`), a comment, or an empty part. Its ask is answered each time.
+ *
+ * Chips still never sees the tool call itself; it reads the words the harness sent in its ask.
+ */
+/** Past this, a command is not read: a standing yes is for the commands a person reads. */
+const LONGEST = 10_000;
+/** What a command is, from an ask's input: its string or its words, or nothing. */
+export function askedCommand(input) {
+    if (typeof input !== "object" || input === null)
+        return undefined;
+    const command = input["command"];
+    if (typeof command === "string")
+        return command.trim() === "" ? undefined : command;
+    if (Array.isArray(command) &&
+        command.length > 0 &&
+        command.every((word) => typeof word === "string" && word !== "")) {
+        return command;
+    }
+    return undefined;
+}
+/** The command's parts, each as its words; nothing for a command this reader can't follow. */
+export function commandParts(command) {
+    if (typeof command !== "string")
+        return command.length === 0 ? undefined : [[...command]];
+    if (command.length > LONGEST)
+        return undefined;
+    const reader = new Reader(command);
+    const parts = reader.read();
+    // A variable set before the program changes what runs, and a shell's own word (`if`, `!`)
+    // runs the words after it, which the parts would not show as a program.
+    const unread = parts?.some((part) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(part[0] ?? "") || KEYWORDS.has(part[0] ?? ""));
+    return unread === false ? parts : undefined;
+}
+/** One pass over a command's characters: `false` from a step means it can't be read. */
+class Reader {
+    command;
+    parts = [];
+    words = [];
+    word;
+    quote;
+    at = 0;
+    constructor(command) {
+        this.command = command;
+    }
+    read() {
+        for (; this.at < this.command.length; this.at += 1) {
+            const char = this.command[this.at];
+            const fine = this.quote === "'"
+                ? this.single(char)
+                : this.quote === '"'
+                    ? this.double(char)
+                    : this.bare(char);
+            if (!fine)
+                return undefined;
+        }
+        if (this.quote !== undefined)
+            return undefined;
+        this.endWord();
+        if (this.words.length > 0)
+            this.parts.push(this.words);
+        // A chain left open (`ls &&`, `ls |`) is not a command; a last `;` or new line is.
+        else if (this.parts.length === 0 || !/[;\n]\s*$/.test(this.command))
+            return undefined;
+        return this.parts;
+    }
+    /** Inside single quotes everything is itself, up to the closing quote. */
+    single(char) {
+        if (char === "'")
+            this.quote = undefined;
+        else
+            this.word += char;
+        return true;
+    }
+    /** Inside double quotes a shell still runs `$` and backticks, so those can't be read. */
+    double(char) {
+        if (char === '"')
+            this.quote = undefined;
+        else if (char === "$" || char === "`")
+            return false;
+        else if (char === "\\" && '"\\$`'.includes(this.command[this.at + 1] ?? "")) {
+            this.at += 1;
+            this.word += this.command[this.at];
+        }
+        else
+            this.word += char;
+        return true;
+    }
+    bare(char) {
+        if (char === "'" || char === '"') {
+            this.quote = char;
+            this.word ??= "";
+            return true;
+        }
+        if (char === "\\")
+            return this.escaped();
+        if (char === " " || char === "\t") {
+            this.endWord();
+            return true;
+        }
+        const between = this.between(char);
+        if (between !== undefined)
+            return between;
+        if ("<>()&$`{}".includes(char) || (char === "#" && this.word === undefined))
+            return false;
+        this.word = (this.word ?? "") + char;
+        return true;
+    }
+    /** Where one part ends and the next starts, if it does here: `&&`, `||`, `;`, `|`, a new line. */
+    between(char) {
+        const pair = this.command.slice(this.at, this.at + 2);
+        if (pair === "&&" || pair === "||") {
+            this.at += 1;
+            return this.endPart();
+        }
+        return char === ";" || char === "|" || char === "\n" ? this.endPart() : undefined;
+    }
+    /** A backslash outside quotes makes the next character itself; at the end it continues a line. */
+    escaped() {
+        const next = this.command[this.at + 1];
+        if (next === undefined || next === "\n")
+            return false;
+        this.word = (this.word ?? "") + next;
+        this.at += 1;
+        return true;
+    }
+    endWord() {
+        if (this.word !== undefined)
+            this.words.push(this.word);
+        this.word = undefined;
+    }
+    /** A part ends at `&&`, `||`, `;`, `|` or a new line; an empty one can't be read. */
+    endPart() {
+        this.endWord();
+        if (this.words.length === 0)
+            return false;
+        this.parts.push(this.words);
+        this.words = [];
+        return true;
+    }
+}
+/** The shell's own words, which run what follows them rather than being a program. */
+const KEYWORDS = new Set([
+    "!",
+    "if",
+    "then",
+    "else",
+    "elif",
+    "fi",
+    "for",
+    "while",
+    "until",
+    "do",
+    "done",
+    "case",
+    "esac",
+    "select",
+    "function",
+    "coproc",
+    "[[",
+    "]]",
+]);
+/**
+ * The commands a standing yes is never given for (ADR 0239): they can't be undone, leave the
+ * machine, act as somebody else, or run whatever code or command they are given. A part matches
+ * an entry of one word when its program is that word, and an entry of two when its program is the
+ * first and the second is among its words, wherever it stands (`git -C dir push`).
+ */
+export const NEVER_STANDING = [
+    ["rm"],
+    ["rmdir"],
+    ["sudo"],
+    ["su"],
+    ["doas"],
+    ["chmod"],
+    ["chown"],
+    ["dd"],
+    ["mkfs"],
+    ["kill"],
+    ["killall"],
+    ["pkill"],
+    ["shutdown"],
+    ["reboot"],
+    ["curl"],
+    ["wget"],
+    ["ssh"],
+    ["scp"],
+    ["rsync"],
+    ["git", "push"],
+    ["git", "reset"],
+    ["git", "clean"],
+    ["find", "-exec"],
+    ["find", "-execdir"],
+    ["find", "-ok"],
+    ["find", "-delete"],
+    ["sh", "-c"],
+    ["bash", "-c"],
+    ["zsh", "-c"],
+    ["eval"],
+    ["exec"],
+    ["xargs"],
+    ["env"],
+    ["command"],
+    ["builtin"],
+    ["nohup"],
+    ["time"],
+    ["timeout"],
+    ["nice"],
+    ["watch"],
+    ["node", "-e"],
+    ["node", "--eval"],
+    ["python", "-c"],
+    ["python3", "-c"],
+    ["perl", "-e"],
+    ["ruby", "-e"],
+];
+/** A program's own name, from a path to it: `/bin/rm` is `rm`. */
+function programOf(word) {
+    return word.slice(word.lastIndexOf("/") + 1);
+}
+/** The listed command a part uses, in words (`rm`, `git push`); nothing for one not listed. */
+export function neverStanding(parts) {
+    for (const part of parts) {
+        const program = programOf(part[0] ?? "");
+        const rest = part.slice(1);
+        const listed = NEVER_STANDING.find(([first, second]) => first === program && (second === undefined || rest.includes(second)));
+        if (listed !== undefined)
+            return listed.join(" ");
+    }
+    return undefined;
+}
+/** How a part starts, as a standing yes remembers it: its first two words, or its one. */
+export function startOf(part) {
+    return part.slice(0, 2);
+}
+/** Each part's start, once each, in the command's order. */
+export function commandStarts(parts) {
+    const starts = [];
+    for (const part of parts) {
+        const start = startOf(part);
+        if (!starts.some((kept) => sameWords(kept, start)))
+            starts.push(start);
+    }
+    return starts;
+}
+/** Whether the part begins with these words, each exactly. */
+export function startsWith(part, start) {
+    return start.length > 0 && start.length <= part.length && start.every((w, i) => part[i] === w);
+}
+function sameWords(one, other) {
+    return one.length === other.length && one.every((w, i) => other[i] === w);
+}
+export function standingOffer(input) {
+    const command = askedCommand(input);
+    if (command === undefined)
+        return undefined;
+    const parts = commandParts(command);
+    if (parts === undefined)
+        return { kind: "unreadable" };
+    const never = neverStanding(parts);
+    if (never !== undefined)
+        return { kind: "never", command: never };
+    return { kind: "starts", starts: commandStarts(parts) };
+}
+//# sourceMappingURL=commands.js.map

package/dist/src/commands.js.map

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

package/dist/src/connectors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The server, as the people paired to it see it, and the gallery a person picks an agent from
+ * (ADRs 0170, 0171).
+ *
+ * - **`GET /v1/server`** says which machine Chips runs on ("Arjun's Mac mini"), its version, and
+ *   how far it reaches: the welcome and the setup card say it.
+ * - **`GET /v1/connectors`** hands out the gallery's cards. They are docs content: each connector
+ *   lives with its harness (ADR 0051), and the docs say what each is and how it connects. The
+ *   server reads the docs' `connectors.json` from wherever it was told (`CHIPS_CONNECTORS`) and
+ *   passes it on. Chips names no harness itself, so with nothing to read the gallery is the two
+ *   ways in the apps carry: your own harness, and anything with HTTP.
+ *
+ * A card's `command` and `sentence` carry `{link}` where a join link (ADR 0122) goes:
+ * `fillLink` puts it there. The sentence is what a person pastes into the chat where they already
+ * talk to their agent, so that the agent connects itself.
+ */
+import { z } from "zod";
+/** What `{link}` is spelled as in a card's command and sentence. */
+export declare const LINK_SLOT = "{link}";
+/** A connector's line or sentence with the link in it. */
+export declare function fillLink(template: string, link: string): string;
+/** How a connector is brought in, which decides what its card offers. */
+export declare const connectorKind: z.ZodEnum<{
+    "one-line": "one-line";
+    sdk: "sdk";
+    http: "http";
+    guide: "guide";
+}>;
+export type ConnectorKind = z.infer<typeof connectorKind>;
+export declare const connector: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    line: z.ZodString;
+    needs: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        "one-line": "one-line";
+        sdk: "sdk";
+        http: "http";
+        guide: "guide";
+    }>;
+    command: z.ZodOptional<z.ZodString>;
+    sentence: z.ZodOptional<z.ZodString>;
+    package: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    docs: z.ZodOptional<z.ZodURL>;
+    published: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type Connector = z.infer<typeof connector>;
+/** The most cards the gallery shows: the docs are a list, not a store. */
+export declare const CONNECTORS_MAX = 24;
+/**
+ * The cards in a `connectors.json`, keeping each that reads and leaving out each that doesn't: a
+ * bad entry in the docs costs that card, never the gallery. Nothing that isn't a list is nothing.
+ */
+export declare function readConnectors(raw: unknown): Connector[];
+export declare const connectorsAnswer: z.ZodObject<{
+    connectors: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        line: z.ZodString;
+        needs: z.ZodOptional<z.ZodString>;
+        kind: z.ZodEnum<{
+            "one-line": "one-line";
+            sdk: "sdk";
+            http: "http";
+            guide: "guide";
+        }>;
+        command: z.ZodOptional<z.ZodString>;
+        sentence: z.ZodOptional<z.ZodString>;
+        package: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        docs: z.ZodOptional<z.ZodURL>;
+        published: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    read_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ConnectorsAnswer = z.infer<typeof connectorsAnswer>;
+export declare const serverFacts: z.ZodObject<{
+    machine: z.ZodString;
+    version: z.ZodString;
+    public_url: z.ZodURL;
+    relay: z.ZodObject<{
+        url: z.ZodNullable<z.ZodString>;
+        status: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ServerFacts = z.infer<typeof serverFacts>;
+//# sourceMappingURL=connectors.d.ts.map

package/dist/src/connectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectors.d.ts","sourceRoot":"","sources":["../../src/connectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,oEAAoE;AACpE,eAAO,MAAM,SAAS,WAAW,CAAC;AAElC,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AAID,yEAAyE;AACzE,eAAO,MAAM,aAAa;;;;;EAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;iBAkDwD,CAAC;AAC/E,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,0EAA0E;AAC1E,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,EAAE,CAkBxD;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;iBAQ2C,CAAC;AACzE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,WAAW;;;;;;;;iBAUkE,CAAC;AAC3F,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/src/connectors.js

@@ -0,0 +1,119 @@
+/**
+ * The server, as the people paired to it see it, and the gallery a person picks an agent from
+ * (ADRs 0170, 0171).
+ *
+ * - **`GET /v1/server`** says which machine Chips runs on ("Arjun's Mac mini"), its version, and
+ *   how far it reaches: the welcome and the setup card say it.
+ * - **`GET /v1/connectors`** hands out the gallery's cards. They are docs content: each connector
+ *   lives with its harness (ADR 0051), and the docs say what each is and how it connects. The
+ *   server reads the docs' `connectors.json` from wherever it was told (`CHIPS_CONNECTORS`) and
+ *   passes it on. Chips names no harness itself, so with nothing to read the gallery is the two
+ *   ways in the apps carry: your own harness, and anything with HTTP.
+ *
+ * A card's `command` and `sentence` carry `{link}` where a join link (ADR 0122) goes:
+ * `fillLink` puts it there. The sentence is what a person pastes into the chat where they already
+ * talk to their agent, so that the agent connects itself.
+ */
+import { z } from "zod";
+/** What `{link}` is spelled as in a card's command and sentence. */
+export const LINK_SLOT = "{link}";
+/** A connector's line or sentence with the link in it. */
+export function fillLink(template, link) {
+    return template.split(LINK_SLOT).join(link);
+}
+const words = (most) => z.string().trim().min(1).max(most);
+/** How a connector is brought in, which decides what its card offers. */
+export const connectorKind = z
+    .enum(["one-line", "sdk", "http", "guide"])
+    .describe("`one-line`: a command to run where the harness runs; `sdk`: code on @chipschat/harness; `http`: a key and curl lines; `guide`: a page to follow.");
+export const connector = z
+    .object({
+    id: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]{0,40}$/)
+        .describe("The docs' name for it, lower case."),
+    name: words(60).describe("What a person calls it."),
+    line: words(120).describe("One line under the name: where it runs, what it needs."),
+    needs: words(120)
+        .optional()
+        .describe('What has to be on the computer first, said after "You need": its harness installed and running as its bridge needs. Chips for Mac says it under Connect.'),
+    kind: connectorKind,
+    command: words(400)
+        .optional()
+        .describe("What to run where the harness runs, with `{link}` where the link goes."),
+    sentence: words(600)
+        .optional()
+        .describe("What to say to the agent so it connects itself, with `{link}` in it."),
+    package: z
+        .string()
+        .regex(/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*@\d{1,4}$/)
+        .optional()
+        .describe("The npm package its bridge is published as and the major that speaks this server's protocol, `@chipschat/hermes@1`: `chips connect <id>` fetches the newest release of that major (ADR 0218)."),
+    args: z
+        .array(z.string().regex(/^[^-\s][^\s]{0,199}$/))
+        .max(4)
+        .optional()
+        .describe("What `chips connect <id>` passes its bridge before the link is used, a config's path for one: `~/.chips-acp/codex.json`."),
+    capabilities: z
+        .array(z.string().regex(/^[a-z][a-z_]{0,39}$/))
+        .max(16)
+        .optional()
+        .describe("What its connector needs to do its job (ADR 0046): a link made from the card starts with these on."),
+    docs: z
+        .url({ protocol: /^https?$/ })
+        .optional()
+        .describe("Its page in the docs."),
+    published: z
+        .boolean()
+        .optional()
+        .describe("False while its command can't be run by somebody outside yet."),
+})
+    .describe("A card in the gallery a person brings an agent from (ADR 0171).");
+/** The most cards the gallery shows: the docs are a list, not a store. */
+export const CONNECTORS_MAX = 24;
+/**
+ * The cards in a `connectors.json`, keeping each that reads and leaving out each that doesn't: a
+ * bad entry in the docs costs that card, never the gallery. Nothing that isn't a list is nothing.
+ */
+export function readConnectors(raw) {
+    const list = Array.isArray(raw)
+        ? raw
+        : raw !== null &&
+            typeof raw === "object" &&
+            Array.isArray(raw.connectors)
+            ? raw.connectors
+            : [];
+    const kept = [];
+    const seen = new Set();
+    for (const each of list) {
+        const read = connector.safeParse(each);
+        if (!read.success || seen.has(read.data.id))
+            continue;
+        seen.add(read.data.id);
+        kept.push(read.data);
+        if (kept.length === CONNECTORS_MAX)
+            break;
+    }
+    return kept;
+}
+export const connectorsAnswer = z
+    .object({
+    connectors: z.array(connector).max(CONNECTORS_MAX),
+    read_at: z
+        .string()
+        .optional()
+        .describe("When the server last read them, as an ISO timestamp. Absent: never."),
+})
+    .describe("`GET /v1/connectors`: the gallery's cards, from the docs.");
+export const serverFacts = z
+    .object({
+    machine: words(120).describe("The machine Chips runs on, as its owner named it."),
+    version: z.string(),
+    public_url: z.url({ protocol: /^https?$/ }).describe("Where another device reaches it."),
+    relay: z.object({
+        url: z.string().nullable(),
+        status: z.string().describe("`off`, `connecting`, `connected` …, as `/v1/health` says it."),
+    }),
+})
+    .describe("`GET /v1/server`: the server, as the people paired to it see it (ADR 0170).");
+//# sourceMappingURL=connectors.js.map

package/dist/src/connectors.js.map

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