pinecall 0.1.0

package/dist/cli/load.js

@@ -0,0 +1,99 @@
+/** Loading a tenant's agent file from the CLI: the TypeScript loader, the class, and its own source. */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Agent, setCall } from "../agent/agent.js";
+import { describe } from "../agent/docstrings.js";
+import { CallWorld } from "../call/call.js";
+import { slugOf } from "../runtime/connect.js";
+import { groundingOf } from "../runtime/grounding.js";
+/**
+ * Where an agent lives when nobody said. A class whose `render()` returns JSX is written in
+ * `agent.tsx`, which is what every example and every generator writes; `agent.ts` still loads, for
+ * a class that renders nothing. The first that is there wins, and a usage line names the first.
+ */
+export const DEFAULT_AGENTS = ["agent.tsx", "agent.ts"];
+let registered = false;
+/** Register tsx, once per process: the tenant writes .ts and .tsx and never a build step. */
+// `pinecall run` on a fresh clone must work with `pnpm i` and nothing else. Registering is done
+// once per process and only when a tenant's file is actually loaded, so `pinecall <planned group>`
+// pays nothing for it. Exported because a persona is a tenant's .ts file too — cli/testing/caller.ts.
+export async function useTypeScript() {
+    if (registered)
+        return;
+    const { register } = await import("tsx/esm/api");
+    register();
+    registered = true;
+}
+/**
+ * Load an agent file: import its default export and hand the class its own source.
+ *
+ * The source is not a nicety. A class docstring sits ABOVE the class, where `Ctor.toString()`
+ * cannot see it, and the parameter types are gone by the time the file is a module — so the identity
+ * block would open without its first line and the tools would carry untyped arguments. `describe`
+ * is the one call that puts both back, and this is the only place that has the text to give it.
+ */
+export async function load(file) {
+    const path = file === undefined ? theAgentHere() : resolve(file);
+    if (!existsSync(path))
+        throw new Error(`no agent at ${path}`);
+    await useTypeScript();
+    const module_ = (await import(pathToFileURL(path).href));
+    const ctor = module_.default;
+    if (typeof ctor !== "function")
+        throw new Error(`${path} has no default-exported Agent class`);
+    const source = readFileSync(path, "utf8");
+    describe(ctor, source, path);
+    // What the class says it knows is checked here, where its path is in hand: a knowledge file that
+    // is not there, or `docs` still written as a glob, is refused before a prompt is printed or a
+    // gateway is knocked at — `pinecall prompt` never mounts, and it must say so too.
+    groundingOf(new ctor(), path);
+    return { ctor: ctor, file: path, source };
+}
+/**
+ * One instance of the loaded class with a line to answer on: what the pages that print a prompt
+ * render. A `render()` may read `this.call`, and a page that could not answer that question would
+ * be a page about a call that cannot happen.
+ */
+export function instanceFor(loaded, channel = "web") {
+    const agent = new loaded.ctor();
+    setCall(agent, new CallWorld({ id: "", contact: "", channel }, () => undefined));
+    return agent;
+}
+/** What `mount` is given for a loaded agent: the client, the source and the file it came from. */
+export function mountOptions(loaded, pc) {
+    return { pc, source: loaded.source, file: loaded.file };
+}
+// Nobody named a file. Looking for both names and saying so is the whole of it: a directory with
+// neither is a directory somebody typed the verb in by mistake, and the refusal has to say where
+// it looked rather than "no agent at /…/agent.tsx" for a project written in .ts.
+function theAgentHere() {
+    const found = DEFAULT_AGENTS.map((name) => resolve(name)).find((path) => existsSync(path));
+    if (found !== undefined)
+        return found;
+    throw new Error(`no agent here: looked for ${DEFAULT_AGENTS.join(" and ")} in ${process.cwd()}`);
+}
+// The slug of the agent this terminal is standing in, read the way `run` reads it, so no two verbs
+// disagree about whose directory this is. No file here is not an error: it is a terminal outside
+// any agent's directory, and the verb that asked says what it needs instead.
+// `--agent` used to mean a SLUG in three verbs and a FILE in six, which is a flag with two
+// meanings and no way to tell which one you got. It names a slug everywhere now, and `--file` is
+// the file — so a path typed where a slug is taken is a person who learnt the old spelling, and
+// they are told the new one rather than being sent to look for an agent called "agent.tsx".
+const A_PATH = /\.tsx?$|[/\\]/;
+/** The refusal for a file typed where a slug is taken, or undefined when it is a slug. */
+export function notASlug(said) {
+    if (said === undefined || !A_PATH.test(said))
+        return undefined;
+    return `an agent is named by its slug, not a file: \`--file ${said}\` names the class to load.`;
+}
+export async function agentOfThisDirectory() {
+    try {
+        const loaded = await load();
+        return slugOf(loaded.ctor);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=load.js.map

package/dist/cli/load.js.map

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

package/dist/cli/login.d.ts

@@ -0,0 +1,30 @@
+/** `pinecall login [gateway]`: signed in through a browser, and the key it mints kept in ~/.pinecall. */
+import type { Group } from "./groups.js";
+export declare const group: Group;
+/** What login can be told besides the argv. Tests only: where to print, and how time passes. */
+export interface Signing {
+    out?: NodeJS.WritableStream;
+    err?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+    /** How the link is put in front of the person. A test watches instead of opening a browser. */
+    open?: (url: string) => void;
+    /** How long between asks, and how long before giving up. A test does not wait two seconds. */
+    every?: number;
+    until?: number;
+}
+/** Sign in through a browser, or keep a machine's key; either way it is proved before it is kept. */
+export declare function login(argv: string[], how?: Signing): Promise<number>;
+/**
+ * Which gateway this login is for, and the line to print when nobody said.
+ *
+ * A URL nobody typed is the cloud's, and that is said OUT LOUD before anything is kept: a person
+ * who meant their own box has to be able to see that this one was assumed, in the line above the
+ * link, rather than discovering it in `pinecall whoami` tomorrow.
+ */
+export declare function theGateway(named: string | undefined): {
+    url: string;
+    assumed?: string;
+};
+/** Where the person signs this terminal in: the gateway's own page, carrying the word. */
+export declare function signingIn(gateway: string, code: string): string;
+//# sourceMappingURL=login.d.ts.map

package/dist/cli/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/cli/login.ts"],"names":[],"mappings":"AAAA,yGAAyG;AASzG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAczC,eAAO,MAAM,KAAK,EAAE,KAoBnB,CAAC;AAEF,gGAAgG;AAChG,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,+FAA+F;IAC/F,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,8FAA8F;IAC9F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qGAAqG;AACrG,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,OAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAyC9E;AAgCD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAMvF;AAED,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/cli/login.js

@@ -0,0 +1,158 @@
+/** `pinecall login [gateway]`: signed in through a browser, and the key it mints kept in ~/.pinecall. */
+import { hostname } from "node:os";
+import { parseArgs } from "node:util";
+import { openInABrowser } from "./browser.js";
+import { pinecallHome, writeGateway } from "./credentials.js";
+import { nameFor, readConfig, writeProfile } from "./profiles.js";
+import { CLOUD_URL } from "./env.js";
+import { aLineOfStdin } from "./secret.js";
+import { asked } from "./testing/gateway.js";
+import { orgOf, refusal, whoIs } from "./whoami.js";
+const USAGE = "usage: pinecall login [gateway-url] [--key-stdin]";
+// How often the terminal asks, and for how long. The gateway's word lives ten minutes, so this
+// gives up a little after it does rather than polling a word that cannot come back.
+const EVERY_MS = 2_000;
+const GIVE_UP_MS = 11 * 60 * 1_000;
+const TOOK_TOO_LONG = "nobody approved this terminal: `pinecall login` again when you are ready";
+export const group = {
+    purpose: "sign in through a browser and keep the key it mints",
+    usage: `${USAGE}
+
+  Prints a link and opens it. You sign in there — in a browser, where a password belongs — and
+  the page hands this terminal a key of its OWN, minted for you and labelled as this machine, so
+  it is revoked on its own from the Keys screen. Nothing types a password into a shell, and the
+  day your org signs in with Google this verb does not change.
+
+  With no URL it is ${CLOUD_URL}, and it says so. Name another for your own box.
+
+  The key it keeps is this machine's SANDBOX key, so \`pinecall run\` and \`pinecall chat\`
+  answer in a world of your own and never in the one your customers call.
+
+  --key-stdin reads a KEY from one line of stdin instead, for a machine: a server, a CI job, a
+  container. That is what \`pinecall keys issue\` mints, and it writes the same profile — so a
+  machine and a person hold a key the same way, in a 0600 file read once rather than in an
+  environment every child process and every \`ps\` can read. PINECALL_HOME says where that file
+  goes, and it is the only variable this CLI reads.`,
+    run: login,
+};
+/** Sign in through a browser, or keep a machine's key; either way it is proved before it is kept. */
+export async function login(argv, how = {}) {
+    const out = how.out ?? process.stdout;
+    const err = how.err ?? process.stderr;
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { "key-stdin": { type: "boolean", default: false }, as: { type: "string" } },
+    });
+    const { url, assumed } = theGateway(positionals[0]);
+    if (assumed !== undefined)
+        out.write(`${assumed}\n`);
+    const key = values["key-stdin"] === true ? (await aLineOfStdin()).trim() : await throughABrowser(url, how, out, err);
+    if (key === null)
+        return 1;
+    if (key === "") {
+        err.write("no key was typed: nothing was kept\n");
+        return 2;
+    }
+    // Proved before it is kept, whichever way it was got: a key that opens nothing is a file a
+    // person will trust tomorrow and a refusal they will not understand.
+    let who;
+    try {
+        who = await whoIs({ url, apiKey: key });
+    }
+    catch (refused) {
+        err.write(`${refusal(refused)}\n`);
+        return 1;
+    }
+    const environment = how.env ?? process.env;
+    const home = pinecallHome(environment);
+    // The slug and not the id, in the file as on the line: a person opening the config to see which
+    // org a gateway is has to read a word they recognise.
+    //
+    // It is kept twice on purpose, for exactly one release: `config.json` is what every verb reads
+    // now, and `credentials` is what v1's CLI on this same machine still reads. The second write
+    // goes with the second half of this change.
+    const name = values.as ?? nameFor(url, readConfig(home));
+    writeProfile(name, { url, key, org: orgOf(who), env: who.env }, home);
+    writeGateway(url, { api_key: key, org: orgOf(who) }, home);
+    out.write(`▸ ${name} · ${url} · org ${orgOf(who)} · ${who.env}\n`);
+    return 0;
+}
+/**
+ * The dance: a word this terminal asks for, a link the person opens, and the key left behind.
+ *
+ * The terminal never sees the password and the browser never sees this key until it is minted —
+ * what travels in the URL is a word that dies in ten minutes and on first collection. Null once
+ * the refusal has been printed.
+ */
+async function throughABrowser(url, how, out, err) {
+    const door = { url, apiKey: "" };
+    let opened;
+    try {
+        opened = await asked(door, "/v1/login/pairings", {
+            method: "POST",
+            body: { device: thisMachine() },
+        });
+    }
+    catch (refused) {
+        err.write(`${refusal(refused)}\n`);
+        return null;
+    }
+    const link = signingIn(url, opened.code);
+    out.write(`\nopen this to sign in:\n${link}\n\nwaiting…\n`);
+    (how.open ?? openInABrowser)(link);
+    return await collected(door, opened.code, how, err);
+}
+/**
+ * Which gateway this login is for, and the line to print when nobody said.
+ *
+ * A URL nobody typed is the cloud's, and that is said OUT LOUD before anything is kept: a person
+ * who meant their own box has to be able to see that this one was assumed, in the line above the
+ * link, rather than discovering it in `pinecall whoami` tomorrow.
+ */
+export function theGateway(named) {
+    if (named !== undefined)
+        return { url: named };
+    return {
+        url: CLOUD_URL,
+        assumed: `gateway  ${CLOUD_URL}   (the default — \`pinecall login <url>\` for your own box)`,
+    };
+}
+/** Where the person signs this terminal in: the gateway's own page, carrying the word. */
+export function signingIn(gateway, code) {
+    return `${gateway.replace(/\/$/, "")}/cli?c=${encodeURIComponent(code)}`;
+}
+/** Ask until the browser has answered, the word is gone, or nobody ever opened the link. */
+async function collected(door, code, how, err) {
+    const every = how.every ?? EVERY_MS;
+    const until = Date.now() + (how.until ?? GIVE_UP_MS);
+    while (Date.now() < until) {
+        try {
+            // 202 is a 2xx, so this is an empty body and not a refusal: nobody has approved the card
+            // yet. A refusal here is the word being gone — collected, or expired — and it ends the wait.
+            const answered = await asked(door, `/v1/login/pairings/${code}/key`);
+            if (answered?.key !== undefined)
+                return answered.key;
+        }
+        catch (refused) {
+            err.write(`${refusal(refused)}\n`);
+            return null;
+        }
+        await after(every);
+    }
+    err.write(`${TOOK_TOO_LONG}\n`);
+    return null;
+}
+/** What this terminal calls itself, so the card names it and the key is labelled by it. */
+function thisMachine() {
+    try {
+        return hostname();
+    }
+    catch {
+        return "cli";
+    }
+}
+function after(ms) {
+    return new Promise((rung) => setTimeout(rung, ms));
+}
+//# sourceMappingURL=login.js.map

package/dist/cli/login.js.map

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

package/dist/cli/machine.d.ts

@@ -0,0 +1,8 @@
+/** The machine a developer is writing, on one page: the stage the agent is in, and what it shows. */
+/**
+ * Every tool the class declares, the visible ones filled in, each with what gates it. The model
+ * never reads this — it only ever sees the filled ones — but the person writing the class does,
+ * and the page is what turns "why is book not there" into a glance.
+ */
+export declare function showMachine(agent: object): string;
+//# sourceMappingURL=machine.d.ts.map

package/dist/cli/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../src/cli/machine.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAMrG;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWjD"}

package/dist/cli/machine.js

@@ -0,0 +1,41 @@
+/** The machine a developer is writing, on one page: the stage the agent is in, and what it shows. */
+import { stageOf, stagesOf } from "../agent/stages.js";
+import { toolsOf, visibleToolsOf } from "../agent/tools.js";
+import { headerFor } from "../views/render.js";
+/**
+ * Every tool the class declares, the visible ones filled in, each with what gates it. The model
+ * never reads this — it only ever sees the filled ones — but the person writing the class does,
+ * and the page is what turns "why is book not there" into a glance.
+ */
+export function showMachine(agent) {
+    const visible = new Set(visibleToolsOf(agent).map((declared) => declared.name));
+    const declarations = toolsOf(agent);
+    if (declarations.length === 0)
+        return `${header(agent)}\n\n  this agent declares no tools`;
+    const width = Math.max(...declarations.map((declared) => declared.name.length));
+    const lines = declarations.map((declared) => {
+        const shown = visible.has(declared.name);
+        const mark = shown ? "●" : "○";
+        return `  ${mark} ${declared.name.padEnd(width)}  ${gatedBy(agent, declared.options, shown)}`;
+    });
+    return [header(agent), "", ...lines].join("\n");
+}
+// The stage rides in the header, beside the tools it decides: a class with no stages says nothing
+// there rather than inventing one.
+function header(agent) {
+    const stage = stageOf(agent);
+    return stage === undefined ? headerFor("tools") : `${headerFor("tools")} stage: ${stage}`;
+}
+// What decides this tool, in the words its declaration used: the stages it named, `when(state)` for
+// a predicate, `always` for a tool nothing gates. A staged tool that its own stage does not bring
+// back is the one question this page exists to answer, so it says who said no.
+function gatedBy(agent, options, shown) {
+    const stages = stagesOf(options);
+    if (stages === undefined)
+        return options.when === undefined ? "always" : "when(state)";
+    const here = stageOf(agent);
+    const named = stages.join(" · ");
+    const hiddenInItsOwnStage = !shown && here !== undefined && stages.includes(here);
+    return hiddenInItsOwnStage ? `${named} · when(state) says no` : named;
+}
+//# sourceMappingURL=machine.js.map

package/dist/cli/machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.js","sourceRoot":"","sources":["../../src/cli/machine.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAErG,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,OAAO,EAAE,cAAc,EAA0B,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAChF,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,oCAAoC,CAAC;IAC3F,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAChF,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QAC/B,OAAO,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;IAChG,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,kGAAkG;AAClG,mCAAmC;AACnC,SAAS,MAAM,CAAC,KAAa;IAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,WAAW,KAAK,EAAE,CAAC;AAC5F,CAAC;AAED,oGAAoG;AACpG,kGAAkG;AAClG,+EAA+E;AAC/E,SAAS,OAAO,CAAC,KAAa,EAAE,OAA0B,EAAE,KAAc;IACxE,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC;IACvF,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,mBAAmB,GAAG,CAAC,KAAK,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAClF,OAAO,mBAAmB,CAAC,CAAC,CAAC,GAAG,KAAK,wBAAwB,CAAC,CAAC,CAAC,KAAK,CAAC;AACxE,CAAC"}

package/dist/cli/memory.d.ts

@@ -0,0 +1,26 @@
+/** `pinecall memory <contact> | forget <contact> | eval`: what memory kept about one contact, the right to be forgotten, and how well recall ranks. */
+import type { ContactFact, MemoryScore } from "@pinecall/protocol";
+import type { Group } from "./groups.js";
+import { type Door } from "./testing/gateway.js";
+export declare const DEFAULT_GOLDEN = "memory/golden.json";
+/** The two sentences a golden is refused by, said the same in the terminal and on the page. */
+export declare const NO_GOLDEN: (golden: string) => string;
+export declare const AN_EMPTY_GOLDEN: (golden: string) => string;
+export declare const group: Group;
+/** What the verb can be told besides the argv: where to print, the environment, and how it asks. Tests only. */
+export interface Recalling {
+    out?: NodeJS.WritableStream;
+    err?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+    /** Whether the person said yes to forgetting. A test answers here instead of driving a terminal. */
+    confirm?: (question: string) => Promise<boolean>;
+}
+/** Read the contact and do it: the history on stdout, or one forget after one question. */
+export declare function run(argv: string[], how?: Recalling): Promise<number>;
+/** Every question of a golden asked of recall, and the two figures code computed from the answers. */
+export declare function recalledOn(door: Door, questions: unknown[], k: number | undefined): Promise<MemoryScore>;
+/** What a golden prints: the two figures on one line, then a line per question memory did not answer whole. */
+export declare function recallLines(score: MemoryScore): string[];
+/** One fact as a line: the text, its category when it has one, and — dimmed — when it stopped holding. */
+export declare function factLine(fact: ContactFact, dim: boolean): string;
+//# sourceMappingURL=memory.d.ts.map

package/dist/cli/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/cli/memory.ts"],"names":[],"mappings":"AAAA,uJAAuJ;AAOvJ,OAAO,KAAK,EAAE,WAAW,EAA4B,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAG7F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAS,KAAK,IAAI,EAAE,MAAM,sBAAsB,CAAC;AASxD,eAAO,MAAM,cAAc,uBAAuB,CAAC;AAKnD,+FAA+F;AAC/F,eAAO,MAAM,SAAS,WAAY,MAAM,KAAG,MAAyE,CAAC;AACrH,eAAO,MAAM,eAAe,WAAY,MAAM,KAAG,MACkC,CAAC;AAOpF,eAAO,MAAM,KAAK,EAAE,KAenB,CAAC;AAEF,gHAAgH;AAChH,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,oGAAoG;IACpG,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAClD;AAED,2FAA2F;AAC3F,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,SAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB9E;AAwDD,sGAAsG;AACtG,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAE9G;AAED,+GAA+G;AAC/G,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,CAWxD;AAED,0GAA0G;AAC1G,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAOhE"}

package/dist/cli/memory.js

@@ -0,0 +1,148 @@
+/** `pinecall memory <contact> | forget <contact> | eval`: what memory kept about one contact, the right to be forgotten, and how well recall ranks. */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { parseArgs } from "node:util";
+import { theDoor } from "./env.js";
+import { dayAndTime, theQuestionsIn } from "./knowledge.js";
+import { load } from "./load.js";
+import { asked } from "./testing/gateway.js";
+import { refusal } from "./whoami.js";
+const USAGE = `usage: pinecall memory <contact>
+       pinecall memory forget <contact>
+       pinecall memory eval [golden.json] [--k <n>] [--file agent.tsx]`;
+// The golden beside the agent that answers with those facts: the questions recall is held to, and
+// what each should have brought back. `memory/golden.json` is where `eval` looks when nobody says.
+export const DEFAULT_GOLDEN = "memory/golden.json";
+// The door takes the whole golden and needs no contact: every question carries its own facts.
+const EVAL = "/v1/contacts/memory/eval";
+/** The two sentences a golden is refused by, said the same in the terminal and on the page. */
+export const NO_GOLDEN = (golden) => `no golden at ${golden}: a JSON list of {holds, asks, expects}`;
+export const AN_EMPTY_GOLDEN = (golden) => `${golden} holds no questions: a golden is a JSON list of {holds, asks, expects}`;
+// A fact that a later call superseded is still in the history, and it is drawn dimmer so the
+// current ones read first — on a terminal, that is; a pipe gets the plain line.
+const DIM = "\u001b[2m";
+const PLAIN = "\u001b[0m";
+export const group = {
+    purpose: "what memory kept about a contact, forget it on request, and what a golden says of recall",
+    usage: `${USAGE}
+
+  With a contact — the caller's number, or the id the app named — prints everything memory ever
+  kept about them: the current facts first, then the ones a later call superseded, with the date
+  they stopped holding. forget erases all of it, the right to be forgotten; on a terminal it asks
+  once, and it prints how many facts went.
+
+  eval asks recall every question of a golden — a JSON list of {holds, asks, expects}, where holds
+  is what memory holds about that question's contact — and prints recall@k and nDCG@10, computed by
+  code with no model in the loop, plus every question it did not answer whole. No contact of yours
+  is read or written: each question's facts go to a scratch contact and are deleted again. A golden
+  is fixed and the ranking is the variable: never soften a question so a change can pass.`,
+    run,
+};
+/** Read the contact and do it: the history on stdout, or one forget after one question. */
+export async function run(argv, how = {}) {
+    const out = how.out ?? process.stdout;
+    const err = how.err ?? process.stderr;
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { file: { type: "string" }, k: { type: "string" } },
+    });
+    const [verb, second] = positionals;
+    const door = theDoor(how.env ?? process.env, err);
+    if (door === undefined)
+        return 2;
+    try {
+        if (verb === "eval")
+            return await evaluate(door, second, values.k, values.file, out, err);
+        if (verb === "forget" && second !== undefined) {
+            return await forget(door, second, how.confirm ?? askOnATerminal, out);
+        }
+        if (verb !== undefined && verb !== "forget")
+            return await history(door, verb, out);
+    }
+    catch (refused) {
+        err.write(`${refusal(refused)}\n`);
+        return 1;
+    }
+    err.write(`${USAGE}\n`);
+    return 2;
+}
+async function history(door, contact, out) {
+    const remembered = await asked(door, memoryPath(contact));
+    if (remembered.facts.length === 0) {
+        out.write(`nothing remembered about ${contact}\n`);
+        return 0;
+    }
+    const dim = out.isTTY === true;
+    for (const fact of remembered.facts) {
+        out.write(`${factLine(fact, dim)}\n`);
+    }
+    return 0;
+}
+async function forget(door, contact, confirm, out) {
+    if (!(await confirm(`forget everything memory kept about ${contact}? [y/N] `))) {
+        out.write("nothing forgotten\n");
+        return 0;
+    }
+    const gone = await asked(door, memoryPath(contact), { method: "DELETE" });
+    out.write(`forgotten: ${gone.forgotten}\n`);
+    return 0;
+}
+// A golden is run when somebody changed the vocabulary a fact is written in, the embedder or a
+// knob — never on a caller's clock — so it reads its questions off the disk and asks them in order.
+// No contact of the org is read: each question's facts are the question's own.
+async function evaluate(door, file, k, agent, out, err) {
+    const golden = resolve(file ?? join(dirname((await load(agent)).file), DEFAULT_GOLDEN));
+    if (!existsSync(golden)) {
+        err.write(`${NO_GOLDEN(golden)}\n`);
+        return 2;
+    }
+    const questions = theQuestionsIn(golden);
+    if (questions === null) {
+        err.write(`${AN_EMPTY_GOLDEN(golden)}\n`);
+        return 2;
+    }
+    const score = await recalledOn(door, questions, k === undefined ? undefined : Number(k));
+    out.write(`${recallLines(score).join("\n")}\n`);
+    return score.misses.length === 0 ? 0 : 1;
+}
+/** Every question of a golden asked of recall, and the two figures code computed from the answers. */
+export async function recalledOn(door, questions, k) {
+    return await asked(door, EVAL, { method: "POST", body: { questions, ...(k === undefined ? {} : { k }) } });
+}
+/** What a golden prints: the two figures on one line, then a line per question memory did not answer whole. */
+export function recallLines(score) {
+    const figures = `memory · ${score.model} · ${score.questions} questions · ` +
+        `recall@${score.k} ${score.recall_at_k.toFixed(2)} · nDCG@10 ${score.ndcg_at_10.toFixed(2)} · ` +
+        `${Math.round(score.took_ms)} ms`;
+    return [
+        figures,
+        ...score.misses.map((missed) => `  missed: ${missed.asks} → wanted ${missed.missing.join(", ")}, got ${missed.found[0] ?? "nothing"}`),
+    ];
+}
+/** One fact as a line: the text, its category when it has one, and — dimmed — when it stopped holding. */
+export function factLine(fact, dim) {
+    const said = [`- ${fact.text}`];
+    if (fact.category)
+        said.push(`(${fact.category})`);
+    if (fact.invalidated_at === null)
+        return said.join(" ");
+    said.push(`· until ${dayAndTime(fact.invalidated_at)}`);
+    const line = said.join(" ");
+    return dim ? `${DIM}${line}${PLAIN}` : line;
+}
+function memoryPath(contact) {
+    return `/v1/contacts/${encodeURIComponent(contact)}/memory`;
+}
+// The one question, on a terminal. Off one — a script, CI — nobody is there to answer, and the
+// verb was typed on purpose: it goes ahead.
+async function askOnATerminal(question) {
+    if (!process.stdin.isTTY)
+        return true;
+    const reading = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((typed) => reading.question(question, typed));
+    reading.close();
+    return /^y(es)?$/i.test(answer.trim());
+}
+//# sourceMappingURL=memory.js.map

package/dist/cli/memory.js.map

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

package/dist/cli/numbers.d.ts

@@ -0,0 +1,25 @@
+/** `pinecall numbers list | import | move | drop`: which number reaches which agent, in which world. */
+import type { Group } from "./groups.js";
+/** One door as the listing answers it: the route itself, and which table it came from. */
+interface Door_ {
+    route: {
+        number: string | null;
+        channel: string;
+        agent: string;
+        env: string;
+        managed: boolean;
+    };
+    source: string;
+}
+export declare const group: Group;
+/** What the verb can be told besides the argv: where to print, and which environment. */
+export interface Numbering {
+    out?: NodeJS.WritableStream;
+    err?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function run(argv: string[], how?: Numbering): Promise<number>;
+/** One door as a person reads it: the number, whose it is, where, and who put it there. */
+export declare function aLine(one: Door_): string;
+export {};
+//# sourceMappingURL=numbers.d.ts.map

package/dist/cli/numbers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.d.ts","sourceRoot":"","sources":["../../src/cli/numbers.ts"],"names":[],"mappings":"AAAA,wGAAwG;AAKxG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAezC,0FAA0F;AAC1F,UAAU,KAAK;IACb,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAChG,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD,eAAO,MAAM,KAAK,EAAE,KAenB,CAAC;AAEF,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,SAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB9E;AAaD,2FAA2F;AAC3F,wBAAgB,KAAK,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAKxC"}