balladeer 1.0.0 → 1.0.1

package/dist/session.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The id that ties what an agent was told to what it then wrote.
+ *
+ * A retrieval read happens before the commit exists, so nothing joins the two
+ * on its own. The agent's own working session is what spans them: it reads the
+ * index under this id, and writes the same id into the commit trailer. That is
+ * the whole mechanism, and it lives here rather than on the server because the
+ * server never sees a commit message.
+ *
+ * The id is opaque and says nothing about the work. It is not a secret either:
+ * it is written into commit messages, which is exactly where people will read
+ * it. What it must be is stable across one piece of work and different across
+ * two, which is what the marker file below is for.
+ */
+/**
+ * The shape of a session id, and the line that carries it into a commit.
+ *
+ * Written out here rather than imported. This command is published to npm on
+ * its own and depends on nothing, so the grammar it uses has to live inside it;
+ * a packaging test compares these three against the control plane's own
+ * definitions, so a drift fails here rather than as a token the server refuses
+ * out of a customer's commit message.
+ */
+export declare const AGENT_SESSION_ID_PATTERN: RegExp;
+/** The trailer key an agent writes into the commit or the pull-request body. */
+export declare const AGENT_SESSION_TRAILER = "Balladeer-Session";
+/** The exact line to paste, so every carrier spells the trailer one way. */
+export declare function agentSessionTrailerLine(sessionId: string): string;
+/**
+ * The session id a commit message or pull-request body carries, if it carries
+ * one this release would recognise.
+ *
+ * A body carrying two different session ids is refused rather than resolved:
+ * two answers to "which session wrote this" is not one answer, and guessing
+ * which of them to record would put an invented join in front of a number.
+ */
+export declare function readAgentSessionTrailer(text: string): string | undefined;
+/** Where the current session for a repository is remembered. */
+export declare const SESSION_FILE = "sessions.json";
+/**
+ * How long one session id stays current.
+ *
+ * A working session is a sitting, not a calendar day. Twelve hours is long
+ * enough that a morning's work and the commit that ends it share an id, and
+ * short enough that a machine left running overnight starts the next day's work
+ * under a new one rather than attributing tomorrow's commits to yesterday's
+ * reads. `--new` is the manual answer for anyone whose sitting ends earlier.
+ */
+export declare const SESSION_LIFETIME_MS: number;
+export type SessionMark = Readonly<{
+    /** Which repository this session belongs to, as the credential names it. */
+    repository: string;
+    sessionId: string;
+    startedAt: string;
+}>;
+type SessionFile = {
+    version: 1;
+    sessions: SessionMark[];
+};
+/** A fresh id: the prefix a person can recognise, and 128 bits of nothing else. */
+export declare function mintSessionId(): string;
+export declare function isSessionId(value: string): boolean;
+export declare function readSessionMarks(environment?: NodeJS.ProcessEnv): SessionFile;
+export type CurrentSession = Readonly<{
+    sessionId: string;
+    startedAt: string;
+    /** True when this call minted it, false when it was already current. */
+    minted: boolean;
+}>;
+/**
+ * The session id for this repository right now, minting one when there is none
+ * current.
+ *
+ * Reusing a live one is the point. An agent that asks twice in one sitting must
+ * get the same answer, or its reads and its commit end up under two ids and the
+ * join it exists to make is broken by the act of asking for it.
+ */
+export declare function currentSession(input: Readonly<{
+    repository: string;
+    now: string;
+    forceNew?: boolean;
+    environment?: NodeJS.ProcessEnv;
+}>): CurrentSession;
+export {};

package/dist/session.js

@@ -0,0 +1,135 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertSafeStoreLocation, configHome, writeStoreFile } from "./store.js";
+/**
+ * The id that ties what an agent was told to what it then wrote.
+ *
+ * A retrieval read happens before the commit exists, so nothing joins the two
+ * on its own. The agent's own working session is what spans them: it reads the
+ * index under this id, and writes the same id into the commit trailer. That is
+ * the whole mechanism, and it lives here rather than on the server because the
+ * server never sees a commit message.
+ *
+ * The id is opaque and says nothing about the work. It is not a secret either:
+ * it is written into commit messages, which is exactly where people will read
+ * it. What it must be is stable across one piece of work and different across
+ * two, which is what the marker file below is for.
+ */
+/**
+ * The shape of a session id, and the line that carries it into a commit.
+ *
+ * Written out here rather than imported. This command is published to npm on
+ * its own and depends on nothing, so the grammar it uses has to live inside it;
+ * a packaging test compares these three against the control plane's own
+ * definitions, so a drift fails here rather than as a token the server refuses
+ * out of a customer's commit message.
+ */
+export const AGENT_SESSION_ID_PATTERN = /^bs_[0-9a-f]{32}$/;
+/** The trailer key an agent writes into the commit or the pull-request body. */
+export const AGENT_SESSION_TRAILER = "Balladeer-Session";
+/** The exact line to paste, so every carrier spells the trailer one way. */
+export function agentSessionTrailerLine(sessionId) {
+    return `${AGENT_SESSION_TRAILER}: ${sessionId}`;
+}
+/**
+ * The session id a commit message or pull-request body carries, if it carries
+ * one this release would recognise.
+ *
+ * A body carrying two different session ids is refused rather than resolved:
+ * two answers to "which session wrote this" is not one answer, and guessing
+ * which of them to record would put an invented join in front of a number.
+ */
+export function readAgentSessionTrailer(text) {
+    const pattern = new RegExp(`^[ \\t]*${AGENT_SESSION_TRAILER}[ \\t]*:[ \\t]*(\\S+)[ \\t]*$`, "gim");
+    const found = new Set();
+    for (const match of text.matchAll(pattern)) {
+        const value = match[1];
+        if (value !== undefined && isSessionId(value))
+            found.add(value);
+    }
+    if (found.size !== 1)
+        return undefined;
+    return [...found][0];
+}
+/** Where the current session for a repository is remembered. */
+export const SESSION_FILE = "sessions.json";
+/**
+ * How long one session id stays current.
+ *
+ * A working session is a sitting, not a calendar day. Twelve hours is long
+ * enough that a morning's work and the commit that ends it share an id, and
+ * short enough that a machine left running overnight starts the next day's work
+ * under a new one rather than attributing tomorrow's commits to yesterday's
+ * reads. `--new` is the manual answer for anyone whose sitting ends earlier.
+ */
+export const SESSION_LIFETIME_MS = 12 * 60 * 60 * 1000;
+const EMPTY = { version: 1, sessions: [] };
+/** A fresh id: the prefix a person can recognise, and 128 bits of nothing else. */
+export function mintSessionId() {
+    return `bs_${randomBytes(16).toString("hex")}`;
+}
+export function isSessionId(value) {
+    return AGENT_SESSION_ID_PATTERN.test(value);
+}
+function sessionPath(environment) {
+    return join(configHome(environment), SESSION_FILE);
+}
+export function readSessionMarks(environment = process.env) {
+    let raw;
+    try {
+        raw = readFileSync(sessionPath(environment), "utf8");
+    }
+    catch {
+        return { version: 1, sessions: [] };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const sessions = Array.isArray(parsed.sessions) ? parsed.sessions : [];
+        // A marker whose id this build would not recognise is dropped rather than
+        // repaired. It can only have come from a copy of this command that spelled
+        // ids differently, and reusing one would put a token the server refuses
+        // into a commit message where nobody would ever look for the cause.
+        return { version: 1, sessions: sessions.filter((mark) => isSessionId(mark.sessionId)) };
+    }
+    catch {
+        return { ...EMPTY, sessions: [] };
+    }
+}
+function writeSessionMarks(file, environment) {
+    assertSafeStoreLocation(configHome(environment), environment);
+    writeStoreFile(SESSION_FILE, `${JSON.stringify(file, null, 2)}\n`, environment);
+}
+/**
+ * The session id for this repository right now, minting one when there is none
+ * current.
+ *
+ * Reusing a live one is the point. An agent that asks twice in one sitting must
+ * get the same answer, or its reads and its commit end up under two ids and the
+ * join it exists to make is broken by the act of asking for it.
+ */
+export function currentSession(input) {
+    const environment = input.environment ?? process.env;
+    const file = readSessionMarks(environment);
+    const existing = file.sessions.find((mark) => mark.repository === input.repository);
+    const age = existing === undefined ? undefined : Date.parse(input.now) - Date.parse(existing.startedAt);
+    const usable = existing !== undefined &&
+        input.forceNew !== true &&
+        age !== undefined &&
+        Number.isFinite(age) &&
+        age >= 0 &&
+        age < SESSION_LIFETIME_MS;
+    if (usable && existing !== undefined) {
+        return { sessionId: existing.sessionId, startedAt: existing.startedAt, minted: false };
+    }
+    const minted = {
+        repository: input.repository,
+        sessionId: mintSessionId(),
+        startedAt: input.now,
+    };
+    writeSessionMarks({
+        version: 1,
+        sessions: [...file.sessions.filter((mark) => mark.repository !== input.repository), minted],
+    }, environment);
+    return { sessionId: minted.sessionId, startedAt: minted.startedAt, minted: true };
+}

package/dist/store.d.ts

@@ -81,6 +81,16 @@ export declare function readCredentials(environment?: NodeJS.ProcessEnv): Creden
  * its mode is set on the open descriptor, and it is flushed before the rename.
  */
 export declare function writeCredentials(credentials: Credentials, environment?: NodeJS.ProcessEnv): void;
+/**
+ * One private file in the store directory, written the same careful way the
+ * credential is.
+ *
+ * Pulled out of `writeCredentials` rather than copied beside it: the session
+ * marker written next to the credential is not a secret, but it is written into
+ * the same directory by the same command, and a second, sloppier writer there
+ * would be the one an attacker pre-plants a symlink for.
+ */
+export declare function writeStoreFile(fileName: string, contents: string, environment?: NodeJS.ProcessEnv): void;
 /** Origins, not URL strings, so `https://host/../` cannot alias a stored entry. */
 export declare function normalizeControlPlane(value: string): string;
 /** At most one pending pairing per control plane, newest wins. */

package/dist/store.js

@@ -124,14 +124,26 @@ export function readCredentials(environment = process.env) {
  * its mode is set on the open descriptor, and it is flushed before the rename.
  */
 export function writeCredentials(credentials, environment = process.env) {
+    writeStoreFile("credentials.json", `${JSON.stringify(credentials, null, 2)}\n`, environment);
+}
+/**
+ * One private file in the store directory, written the same careful way the
+ * credential is.
+ *
+ * Pulled out of `writeCredentials` rather than copied beside it: the session
+ * marker written next to the credential is not a secret, but it is written into
+ * the same directory by the same command, and a second, sloppier writer there
+ * would be the one an attacker pre-plants a symlink for.
+ */
+export function writeStoreFile(fileName, contents, environment = process.env) {
     const directory = ensureStoreDirectory(environment);
-    const path = join(directory, "credentials.json");
-    const temporary = join(directory, `.credentials.${randomBytes(8).toString("hex")}.tmp`);
+    const path = join(directory, fileName);
+    const temporary = join(directory, `.${fileName}.${randomBytes(8).toString("hex")}.tmp`);
     let descriptor;
     try {
         descriptor = openSync(temporary, "wx", 0o600);
         fchmodSync(descriptor, 0o600);
-        writeSync(descriptor, `${JSON.stringify(credentials, null, 2)}\n`);
+        writeSync(descriptor, contents);
         fsyncSync(descriptor);
         closeSync(descriptor);
         descriptor = undefined;

package/dist/wire.d.ts

@@ -5,9 +5,9 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export declare const CLI_VERSION = "1.0.0";
+export declare const CLI_VERSION = "1.0.1";
 export declare const CLIENT_HEADER = "x-balladeer-client";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.0";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.1";
 export declare const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export type DelegatedScope = "repository:enroll" | "agent:issue" | "ci:connect" | "workspace:invite" | "candidate:propose";
 export declare const DELEGATED_SCOPES: readonly DelegatedScope[];
@@ -108,6 +108,21 @@ export type SetupInvitationResponse = Readonly<{
 export type SetupCiRequest = Readonly<{
     eventClasses: readonly ("push" | "pull_request")[];
 }>;
+/**
+ * The GitHub login this machine's `gh` is signed in as.
+ *
+ * Sent so a run started by this person can be shown under their name instead of
+ * a handle nobody has learned. No token is sent, here or anywhere: the login is
+ * read from the GitHub CLI they already signed in to, and Balladeer stores it as
+ * something they said rather than something anyone checked. It grants nothing.
+ * An empty string clears it.
+ */
+export type SetupGithubLoginRequest = Readonly<{
+    login: string;
+}>;
+export type SetupGithubLoginResponse = Readonly<{
+    claimedLogin: string | null;
+}>;
 export type SetupRepositoryView = Readonly<{
     id: string;
     displayName: string;
@@ -193,9 +208,32 @@ export type SetupCandidateResponse = Readonly<{
     reviewUrl: string;
 }>;
 /** The step objects `--json` emits, one per line, and nothing else on stdout. */
+/**
+ * What a run did about Claude desktop chat, on the two steps that can touch it.
+ *
+ * Its own type because both `agent` and `refresh` report it and they must report
+ * it identically: an agent reading either step reads the same three fields.
+ */
+export type ClaudeDesktopStep = Readonly<{
+    status: "connected" | "current" | "absent" | "unsupported" | "refused";
+    key?: string;
+    path?: string;
+    reason?: string;
+}>;
 export type JsonStep = Readonly<{
     step: "explain";
     version: string;
+}> | Readonly<{
+    /**
+     * The GitHub login this machine was signed in as, handed over so a run
+     * this person starts can be shown under their name. `status` says what
+     * happened: `claimed` when it was recorded, `unavailable` when `gh` could
+     * not name a login, and `refused` when the control plane would not take
+     * it. None of the three stops setup.
+     */
+    step: "github_login";
+    status: "claimed" | "unavailable" | "refused";
+    login?: string;
 }> | Readonly<{
     step: "pair";
     status: "pending" | "paired" | "expired" | "denied";
@@ -258,6 +296,15 @@ export type JsonStep = Readonly<{
     /** Present only where this command refused to change one of these files. */
     mcpConfig?: string;
     conventions?: string;
+    /**
+     * What happened to Claude desktop chat, present only where this run had
+     * something to say about it. `connected` and `current` carry the key this
+     * repository's server is named under and the file it was written to;
+     * `absent`, `unsupported` and `refused` carry the sentence saying why
+     * nothing was written, and are only ever reported where the flag asked for
+     * it or the file itself refused the merge.
+     */
+    claudeDesktop?: ClaudeDesktopStep;
 }> | Readonly<{
     step: "ci";
     /**
@@ -284,6 +331,20 @@ export type JsonStep = Readonly<{
     reviewUrl?: string;
     promiseUrl?: string;
 }>
+/**
+ * The one-time qualification setup, minted and written to disk.
+ *
+ * `supersededPackets` is the number of earlier packets this run invalidated,
+ * so a caller can tell an ordinary first preparation from a deliberate
+ * replacement without reading prose. It is zero on the ordinary case.
+ */
+ | Readonly<{
+    step: "qualification";
+    status: "prepared";
+    promiseId: string;
+    metadataPath: string;
+    supersededPackets: number;
+}>
 /**
  * A whole discovered catalog, filed in one run.
  *
@@ -482,6 +543,30 @@ export type JsonStep = Readonly<{
     changed: boolean;
     exitCode: number;
 }>
+/**
+ * The working session an agent reads and commits under.
+ *
+ * `minted` is the difference between "here is a new session" and "you already
+ * have one open": an agent that asked twice must reuse the second answer
+ * rather than treat it as a second session, or its reads and its commit end
+ * up under two ids and the join breaks by the act of asking for it.
+ */
+ | Readonly<{
+    step: "session";
+    sessionId: string;
+    startedAt: string;
+    minted: boolean;
+    /** The exact line to write into the commit or the pull-request body. */
+    trailer: string;
+    changed: boolean;
+}>
+/** One commit recorded as written by one session. */
+ | Readonly<{
+    step: "session_commit";
+    sessionId: string;
+    commitSha: string;
+    changed: boolean;
+}>
 /**
  * One invited address, one line, whatever happened to it.
  *
@@ -582,6 +667,7 @@ export type JsonStep = Readonly<{
     previousConventionsVersion?: number;
     reason?: string;
     message?: string;
+    claudeDesktop?: ClaudeDesktopStep;
 }> | Readonly<{
     step: "whoami";
     session: PairSessionSummary;

package/dist/wire.js

@@ -5,7 +5,7 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export const CLI_VERSION = "1.0.0";
+export const CLI_VERSION = "1.0.1";
 export const CLIENT_HEADER = "x-balladeer-client";
 export const CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;
 export const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "balladeer",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,