@ctrl-spc/cs 0.5.0 → 0.7.0

package/dist/panel3/say.js

@@ -0,0 +1,262 @@
+/**
+ * ═══ AGENT PANEL v3: `cs3 say`, the only way anything reaches the record. ═══
+ *
+ * THIS FILE BELONGS TO AGENT PANEL v3. Nothing outside `src/panel3/` may
+ * import it.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE PRODUCT WRITES THE CARD, WITH NO AGENT ANYWHERE. ═══
+ *
+ * ux.md: "The card IS the acknowledgement. It appears on send... written by the
+ * product on send, before any agent exists. An acknowledgement that waits for a
+ * spawn is not an acknowledgement."
+ *
+ * So this command's whole job is to put the card and the turn on the record and
+ * return. It does not spawn, does not take, does not wait for anything to be
+ * ready, and there is nothing here for a daemon to be up for. Nothing answers
+ * the turn yet, which is why `cs3 show` says out loud that nothing is acting on
+ * the card: that is the record being honest, not this command being unfinished.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY A TITLE IS DERIVED HERE RATHER THAN ASKED FOR.
+ *
+ * `panel3_cards.title` is `not null` and non-blank, because a card with no name
+ * cannot be read on a board. The user typed one thing, so the first line of it
+ * is the card's name. Nothing else exists yet that could name it better, and a
+ * second `--title` flag would make the user say twice what they said once.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ SEND ORDER IS MEANING, SO A TURN IS ONLY EVER APPENDED. ═══
+ *
+ * ux.md: "'Approve that' followed by 'actually do it differently' reads as a
+ * sequence and is answerable. Unordered, it is two contradictory demands." Every
+ * send is a new row stamped with the time it arrived, and nothing here edits or
+ * replaces one, so the order the user sent in is the order the record holds.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ `--card` NAMING A CARD THAT IS NOT THERE FAILS, AND NEVER CREATES ONE. ═══
+ *
+ * The two behaviours are different requests: `say` starts a request, `say
+ * --card` continues one. Falling back from the second to the first would put the
+ * user's message on a brand new card while they believed they had answered on
+ * the old one, which is the fenced-off answer ux.md spends a section on, arrived
+ * at by a different route.
+ */
+// The runtime import comes FIRST, deliberately: `tsc` elides a type-only import
+// and takes the leading comment with it, so a file whose first statement is
+// `import type` loses its v3 header in the published `dist/`.
+import { at, out, returned, signedInClient } from './client.js';
+const USAGE = 'usage: cs3 say [--card <id>] [--project <id or name>] "<text>"';
+/** Long enough to recognise a request on a board, short enough to be a name. */
+const TITLE_LIMIT = 80;
+// ---------------------------------------------------------------------------
+/**
+ * The arguments after `say`. A bare word that is not a flag is the message, and
+ * a SECOND one is refused rather than joined: `cs3 say hello there` is a message
+ * the shell already split, and quietly gluing it back together would be this
+ * command guessing at what the user typed. Quoting is the fix and the error says
+ * so.
+ */
+function parseArgs(args) {
+    let cardId = null;
+    let project = null;
+    const words = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--card') {
+            i += 1;
+            const value = args[i];
+            // A FLAG IS NOT A CARD ID. Swallowing the next token whatever it is sends
+            // `cs3 say --card --help "x"` to Postgres and surfaces "invalid input
+            // syntax for type uuid", which is a real error and the wrong one: the
+            // truth is that no card was named.
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error(`--card needs a card id. ${USAGE}`);
+            }
+            cardId = value;
+        }
+        else if (arg === '--project') {
+            i += 1;
+            const value = args[i];
+            // Same reasoning as `--card` above, and it matters more here: a swallowed
+            // flag would be looked up as a project NAME and refused as "no project
+            // called --card", which blames the wrong argument.
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error(`--project needs a project id or name. ${USAGE}`);
+            }
+            project = value;
+        }
+        else if (arg.startsWith('--')) {
+            throw new Error(`unknown option ${arg}. ${USAGE}`);
+        }
+        else {
+            words.push(arg);
+        }
+    }
+    /* ═══ NAMING A PROJECT FOR A CARD THAT ALREADY EXISTS IS REFUSED, NOT
+       IGNORED. ═══ A card is filed once, when it is created; `--card` continues a
+       request that is already filed somewhere. Accepting both and silently using
+       neither would have somebody believe they had moved a card. Moving one is a
+       different act and this build does not have it. */
+    if (cardId && project) {
+        throw new Error('a card is already filed under its project, so --project cannot be given with --card. '
+            + `${USAGE}`);
+    }
+    if (words.length === 0)
+        throw new Error(`say what? ${USAGE}`);
+    if (words.length > 1) {
+        throw new Error(`quote the message as one argument, got ${words.length}. ${USAGE}`);
+    }
+    const message = words[0];
+    // A blank message would produce a blank title, which the table rejects, and a
+    // turn nobody could read. Refused here so the reason names the message rather
+    // than a check constraint.
+    if (message.trim() === '')
+        throw new Error(`the message is empty. ${USAGE}`);
+    return { cardId, project, message };
+}
+/** The first line of what the user typed, as the card's name. */
+function titleFrom(message) {
+    const line = message.trim().split('\n')[0].replace(/\s+/g, ' ').trim();
+    if (line.length <= TITLE_LIMIT)
+        return line;
+    return `${line.slice(0, TITLE_LIMIT - 3).trimEnd()}...`;
+}
+/**
+ * The card `--card` names, or a truthful refusal. `maybeSingle` distinguishes an
+ * absent card from a failed read: it returns null data with no error only when
+ * the row genuinely is not there, and a read that could not run still errors.
+ *
+ * ═══ AND THAT IS WHY THIS ONE DOES NOT GO THROUGH `returned()`. ═══ The shared
+ * guard treats "no error and no data" as a result it does not understand, which
+ * is right for every other call here and wrong for exactly this one: here it is
+ * a fact about the record, and it has its own sentence saying what to do next.
+ */
+async function existingCard(client, cardId) {
+    const { data, error } = await client
+        .from('panel3_cards')
+        .select('id, title')
+        .eq('id', cardId)
+        .maybeSingle();
+    if (error)
+        throw new Error(`could not read card ${cardId}: ${error.message}`);
+    if (!data) {
+        throw new Error(`no card with id ${cardId}. Run \`cs3 say "<text>"\` with no --card to start a new one, `
+            + 'or `cs3 show` to list the cards there are.');
+    }
+    return data;
+}
+/**
+ * ═══ THE CARD'S PROJECT, WHEN THERE IS ONLY ONE IT COULD BE. ═══
+ *
+ * `panel3_cards.project_id` existed from Task 1 and nothing wrote it, so every
+ * card read "no project yet" forever. A column nothing ever writes is not a
+ * nullable column, it is a dead one, and a card that cannot say which project it
+ * belongs to is a card the board cannot file.
+ *
+ * WHAT CAN HONESTLY BE KNOWN AT SEND TIME IS EXACTLY THIS. If the user has one
+ * project, every request they make is about it, and that is a fact about the
+ * record rather than a reading of the words. With two or more, the only clue is
+ * what they typed, and having the product classify a message at send time is the
+ * move ux.md spends a section forbidding: "the moment the product classifies, it
+ * has to be right, and being wrong silently discards something the user said."
+ * So it stays null, `cs3 show` says "no project yet", and that is the truth.
+ *
+ * IT IS A LABEL, NOT A WALL. ux.md: "Project is a filter the coordinator applies,
+ * never a wall it lives inside." Nothing downstream narrows a read to this
+ * project; level 1 sees everything the user has, whatever one card is filed
+ * under.
+ *
+ * `limit(2)` because the question is one-or-more-than-one, and a user with two
+ * hundred projects should not have their acknowledgement wait on a list nobody
+ * reads.
+ *
+ * ═══ AND ARCHIVED PROJECTS ARE NOT PROJECTS IT COULD BE. ═══ Without the
+ * filter, a user with one live project and one they archived last year gets two
+ * rows, so the card silently loses the fact this whole function exists to keep —
+ * and it loses it precisely for the user who has been here long enough to have
+ * archived something. The rule is "the only project it could be", and an
+ * archived one is not one it could be.
+ */
+async function onlyProject(client) {
+    const projects = await returned(client.from('projects').select('id').is('archived_at', null).limit(2), 'read', 'your projects');
+    return projects.length === 1 ? projects[0].id : null;
+}
+/**
+ * ═══ THE PROJECT THE PERSON NAMED, BY ID OR BY NAME. ═══
+ *
+ * A person at a terminal has the name in front of them and the id nowhere, so
+ * refusing anything but a uuid would make the flag unusable by the only people
+ * who can type it. Both are matched against the SHARED `projects` table through
+ * their own RLS, which is the read AGENTS.md allows and the web app makes on
+ * every page.
+ *
+ * ═══ AN UNKNOWN NAME AND AN AMBIGUOUS ONE BOTH REFUSE THE SEND. ═══ Filing the
+ * card somewhere else, or nowhere, would be answering a different request from
+ * the one that was typed: the project decides which checkout the work happens
+ * in. The names are listed back, because the person is one keystroke from the
+ * right one.
+ */
+async function namedProject(client, named) {
+    const projects = await returned(client.from('projects').select('id, name').is('archived_at', null), 'read', 'your projects');
+    const wanted = named.trim().toLowerCase();
+    const matches = projects.filter((p) => p.id === named || (p.name ?? '').trim().toLowerCase() === wanted);
+    if (matches.length === 1)
+        return matches[0].id;
+    const known = projects.map((p) => p.name).sort().join(', ') || 'none';
+    if (matches.length === 0) {
+        throw new Error(`no project of yours is called ${named}. Yours are: ${known}`);
+    }
+    throw new Error(`${matches.length} of your projects are called ${named}, so name it by id instead. `
+        + `Yours are: ${known}`);
+}
+/** A new card, written by the product on send, filed under the project the
+ *  person named, or under their project when there is only one it could be.
+ *  Read first, write once: a failed read refuses the send outright rather than
+ *  writing a card that quietly lost a fact it could have had. */
+async function newCard(client, message, project) {
+    const projectId = project ? await namedProject(client, project) : await onlyProject(client);
+    return returned(client
+        .from('panel3_cards')
+        .insert({ title: titleFrom(message), project_id: projectId })
+        .select('id, title')
+        .single(), 'create', 'the card');
+}
+/** The user's words, appended. `role` is always `user` here: this command is the
+ *  user's, and the agent side of the table belongs to the task that spawns one. */
+async function addTurn(client, cardId, message) {
+    return returned(client
+        .from('panel3_turns')
+        .insert({ card_id: cardId, role: 'user', body: message })
+        .select('id, created_at, addressed_at')
+        .single(), 'add', `the turn to card ${cardId}`);
+}
+// ---------------------------------------------------------------------------
+export async function say(args) {
+    const { cardId, project, message } = parseArgs(args);
+    const client = await signedInClient();
+    const card = cardId
+        ? await existingCard(client, cardId)
+        : await newCard(client, message, project);
+    const isNew = !cardId;
+    let turn;
+    try {
+        turn = await addTurn(client, card.id, message);
+    }
+    catch (error) {
+        // The card is on the record and the message is not. Said out loud, with the
+        // id, because the alternative is a user who believes nothing was written
+        // and a nameless card sitting on their board.
+        const reason = error instanceof Error ? error.message : String(error);
+        if (isNew) {
+            throw new Error(`${reason}\ncard ${card.id} was created and carries no turn. `
+                + `Retry with: cs3 say --card ${card.id} "<text>"`);
+        }
+        throw error;
+    }
+    out(`card   ${card.id}${isNew ? '   NEW' : ''}`);
+    out(`title  ${card.title}`);
+    out(`turn   ${turn.id}   ${at(turn.created_at)}   ${turn.addressed_at ? `addressed ${at(turn.addressed_at)}` : 'NOT ADDRESSED'}`);
+    out();
+    out(`  cs3 show ${card.id}`);
+}

package/dist/panel3/secrets.js

@@ -0,0 +1,98 @@
+/**
+ * ═══ WHAT A RUN READ, AND WHERE IT IS NOT ALLOWED TO GO. ═══
+ *
+ * A credential is attached so an agent can USE it: put it in a header, an
+ * environment variable, a command. That happens inside the agent's own harness
+ * and is none of this file's business. What IS this file's business is
+ * everything the agent then WRITES, because in v3 every word an agent writes is
+ * a row in a hosted database and a line on a card somebody's colleague can open.
+ *
+ * The rule is v2's, and v2 states it in `mcp.ts`: a credential value must never
+ * reach a CLOUD ROW or the PANEL. v3 breaks that rule by default and would have
+ * shipped breaking it, because there is no v3 write that is not a cloud row.
+ *
+ * ═══ TWO HALVES, AND ONLY ONE OF THEM IS THIS FILE. ═══ The other half is the
+ * instruction `get_credential` returns, which tells the agent not to publish the
+ * value. This half is what makes the rule true when the instruction is not
+ * followed, which — v2 recorded it happening in both harnesses — is a thing that
+ * happens. Neither half replaces the other: an instruction alone is a hope, and
+ * a substitution alone would leave the agent believing it had published
+ * something it had not.
+ *
+ * ═══ WHY A COPY OF v2's, AND NOT AN IMPORT. ═══ `panel3/` imports nothing from
+ * v1 or v2, and `panel3-isolation.contract.test.mjs` enforces it. Both are
+ * implementing the same three lines of the same rule.
+ */
+/** run id -> (value -> the credential's STORED name). */
+const secretsByRun = new Map();
+/** Record a value this run was given, so anything it writes can be checked
+ *  against it. An empty value is not recorded: substituting `''` would replace
+ *  every gap in every string. */
+export function rememberSecret(runId, value, name) {
+    if (!runId || !value)
+        return;
+    const forRun = secretsByRun.get(runId) ?? new Map();
+    forRun.set(value, name);
+    secretsByRun.set(runId, forRun);
+}
+/**
+ * Every value this run read, substituted out of text on its way to a row.
+ *
+ * LITERAL, NEVER A RegExp: a real password contains `.`, `+`, `(`, so a pattern
+ * built from one would be malformed or would over-match. `String.replaceAll`
+ * with a STRING needle has no such problem — but its REPLACEMENT still honours
+ * `$&`, `` $` `` and `$'`, so a credential named "Ops $& token" would corrupt
+ * what it replaced. Hence the `$$` escape on the NAME.
+ *
+ * LONGEST FIRST, so a secret that contains another cannot leave a fragment of
+ * the longer one behind after the shorter one has been replaced.
+ *
+ * IDENTITY WHEN THE RUN READ NOTHING, which is nearly every run: the text comes
+ * back byte for byte, so nothing else in v3 has to reason about whether this
+ * touched it.
+ */
+export function redactSecrets(runId, text) {
+    if (!runId || !text)
+        return text;
+    const forRun = secretsByRun.get(runId);
+    if (!forRun || forRun.size === 0)
+        return text;
+    let out = text;
+    for (const value of [...forRun.keys()].sort((a, b) => b.length - a.length)) {
+        if (!out.includes(value))
+            continue;
+        out = out.replaceAll(value, `[redacted: ${(forRun.get(value) ?? 'a credential').replaceAll('$', '$$$$')}]`);
+    }
+    return out;
+}
+/** Drop everything this run read. Called from the run's own completion path,
+ *  which runs on every ending, so a daemon that stays up for days does not keep
+ *  a secret in memory for a run that ended on Tuesday. */
+export function forgetSecrets(runId) {
+    secretsByRun.delete(runId);
+}
+/**
+ * Every string inside a tool call's arguments, redacted, structure untouched.
+ *
+ * ═══ WHY EVERY ARGUMENT OF EVERY TOOL, AND NOT A LIST OF THE RISKY ONES. ═══
+ * No v3 tool has any legitimate reason to be HANDED a secret. They write the
+ * record: a report, an activity line, a question, an answer, a responsibility
+ * for somebody being dispatched, an artifact, a comment. The thing a secret is
+ * FOR — the request that needs it — happens in the harness's own shell, which
+ * does not come through here at all. So the safe set is "all of them", and a
+ * list of risky ones would be a list to keep up to date every time a tool is
+ * added, which is the maintenance nobody does.
+ *
+ * RECURSIVE, because `dispatch` and the artifact tools take nested objects and
+ * arrays, and a secret does not become safe by being one level down.
+ */
+export function redactArgs(runId, args) {
+    if (typeof args === 'string')
+        return redactSecrets(runId, args);
+    if (Array.isArray(args))
+        return args.map((item) => redactArgs(runId, item));
+    if (args && typeof args === 'object') {
+        return Object.fromEntries(Object.entries(args).map(([k, v]) => [k, redactArgs(runId, v)]));
+    }
+    return args;
+}