balladeer 1.0.0 → 1.0.2

package/dist/commands/session.d.ts

@@ -0,0 +1,35 @@
+export type SessionOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    /**
+     * Read the session out of the commit at HEAD and tell Balladeer which commit
+     * it wrote, instead of printing an id.
+     */
+    record: boolean;
+    /** Start a new session even though one is still current. */
+    fresh: boolean;
+    /** The repository whose connection to use, named as `owner/name`. */
+    repo?: string;
+    /** The repository whose connection to use, named by id, as `mcp` takes it. */
+    repository?: string;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    now?: string;
+    write: (text: string) => void;
+}>;
+/**
+ * The id that joins what an agent was told to what it then wrote.
+ *
+ * Retrieval happens before the commit exists, so nothing ties the two together
+ * on its own, and without the tie a red check on Tuesday cannot be read back
+ * against what Balladeer had said on Monday. The agent's own working session
+ * spans both: it reads the index under this id and writes the same id into the
+ * commit it produces.
+ *
+ * `balladeer session` prints the id and the exact line to write.
+ * `balladeer session --record` reads that line back out of the commit at HEAD
+ * and tells Balladeer which commit the session wrote. The commit message itself
+ * never leaves this machine: only the pair of a session id and a forty-
+ * character SHA is sent, and the SHA is a fact CI already reports.
+ */
+export declare function runSession(options: SessionOptions): Promise<number>;

package/dist/commands/session.js

@@ -0,0 +1,131 @@
+import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, } from "../agent.js";
+import { headCommit } from "../git.js";
+import { repositoryHint } from "../repository.js";
+import { AGENT_SESSION_TRAILER, agentSessionTrailerLine, currentSession, readAgentSessionTrailer, } from "../session.js";
+import { StoreError, readCredentials } from "../store.js";
+import { CLI_INVOCATION } from "../wire.js";
+/**
+ * The id that joins what an agent was told to what it then wrote.
+ *
+ * Retrieval happens before the commit exists, so nothing ties the two together
+ * on its own, and without the tie a red check on Tuesday cannot be read back
+ * against what Balladeer had said on Monday. The agent's own working session
+ * spans both: it reads the index under this id and writes the same id into the
+ * commit it produces.
+ *
+ * `balladeer session` prints the id and the exact line to write.
+ * `balladeer session --record` reads that line back out of the commit at HEAD
+ * and tells Balladeer which commit the session wrote. The commit message itself
+ * never leaves this machine: only the pair of a session id and a forty-
+ * character SHA is sent, and the SHA is a fact CI already reports.
+ */
+export async function runSession(options) {
+    const emit = (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const say = (text) => {
+        if (!options.json)
+            options.write(`${text}\n`);
+    };
+    const fail = (reason, message, exitCode) => {
+        if (options.json)
+            emit({ step: "error", reason, message, changed: false, exitCode });
+        else
+            options.write(`${message}\n`);
+        return exitCode;
+    };
+    let credentials;
+    try {
+        credentials = readCredentials(options.environment);
+    }
+    catch (error) {
+        return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
+    }
+    const here = options.repo ?? repositoryHint(options.cwd);
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, here);
+    if (selection.kind === "refused") {
+        const message = selection.missingFor === undefined
+            ? selection.reason
+            : noAgentCredentialSentence(selection.missingFor);
+        return fail("no_agent_credential_on_this_machine", message, 4);
+    }
+    const agent = selection.agent;
+    if (options.record)
+        return recordCommit(options, agent, emit, say, fail);
+    let session;
+    try {
+        session = currentSession({
+            repository: agent.repositoryId,
+            now: options.now ?? new Date().toISOString(),
+            ...(options.fresh ? { forceNew: true } : {}),
+            environment: options.environment,
+        });
+    }
+    catch (error) {
+        // This catch follows successful credential selection and covers only the
+        // local marker write. It must never turn an auth or --record refusal into
+        // permission to continue, or print the freshly generated but unsaved ID.
+        const filesystemError = error instanceof StoreError && error.code === "credential_store_unwritable"
+            ? error.cause
+            : error;
+        const permissionCode = filesystemError instanceof Error && "code" in filesystemError
+            ? filesystemError.code
+            : undefined;
+        if (permissionCode === "EPERM" || permissionCode === "EACCES") {
+            return fail("session_store_permission_denied", `No session stamp was saved: local file permissions refused the write (${permissionCode}). Your saved authenticated connection is unchanged; this command has not checked it with the server. Continue already-authorized MCP reads, coding and explicitly requested capture without the optional session field. Do not invent an ID, add a session trailer, or run session --record for this unsaved stamp. Do not broaden filesystem access or move credentials to retry this write. Capture still requires the person's request or accepted offer, and human meaning approval is unchanged.`, 4);
+        }
+        return fail(error instanceof StoreError ? error.code : "session_store_unwritable", error instanceof StoreError ? error.message : String(error), 4);
+    }
+    const trailer = agentSessionTrailerLine(session.sessionId);
+    emit({
+        step: "session",
+        sessionId: session.sessionId,
+        startedAt: session.startedAt,
+        minted: session.minted,
+        trailer,
+        changed: session.minted,
+    });
+    say(session.sessionId);
+    say("");
+    say(session.minted
+        ? "This is a new session. Pass it to every promise read you make in this repository."
+        : "This session is already open. Pass it to every promise read you make in this repository, and use --new to start a different one.");
+    say(`Then write this line into the commit or pull-request body you produce:`);
+    say("");
+    say(`    ${trailer}`);
+    say("");
+    say(`and run \`${CLI_INVOCATION} session --record\` once the commit exists, so a check that goes red on it can be read back against what you were told before you started. Balladeer is sent the session id and the commit SHA, and nothing else.`);
+    return 0;
+}
+async function recordCommit(options, agent, emit, say, fail) {
+    const head = await headCommit(options.cwd);
+    if (head === undefined) {
+        return fail("no_commit_here", "There is no commit to record: this directory is not a git checkout, or it has no commits yet.", 4);
+    }
+    const sessionId = readAgentSessionTrailer(head.message);
+    if (sessionId === undefined) {
+        // Said in full rather than as a code. The likeliest reader of this line is
+        // an agent that forgot the trailer, and the remedy is one line it can add
+        // to the commit it just made.
+        return fail("no_session_trailer", `The commit at HEAD carries no ${AGENT_SESSION_TRAILER} line this release recognises, so there is nothing to record. Add \`${AGENT_SESSION_TRAILER}: <the id ${CLI_INVOCATION} session prints>\` to the commit message and run this again. A commit carrying two different session ids is refused rather than guessed at.`, 4);
+    }
+    const call = await callAgentTool(agent, "record_session_commit", {
+        session: sessionId,
+        commitSha: head.sha,
+    });
+    reportAgentEnforcementWarning(call, options);
+    if (call.kind !== "result") {
+        return fail(call.kind === "tool_refusal" ? "refused" : call.kind, call.kind === "tool_refusal"
+            ? call.text
+            : `Balladeer could not record this commit (${call.kind}). Nothing was recorded, and running this again after the connection is back is safe: the same pair recorded twice is recorded once.`, 5);
+    }
+    emit({
+        step: "session_commit",
+        sessionId,
+        commitSha: head.sha,
+        changed: true,
+    });
+    say(`Recorded ${head.sha.slice(0, 12)} as written by this session.`);
+    return 0;
+}

package/dist/commands/setup.d.ts

@@ -14,6 +14,12 @@ export type SetupOptions = Readonly<{
      * one checkout can honestly do from here, and the run says so per repository.
      */
     repositories?: readonly string[];
+    /**
+     * Connect an invited teammate to a repository the workspace already holds.
+     * This is deliberately a refusal boundary: if the repository is absent, the
+     * run stops rather than turning an invitation into authority to enroll it.
+     */
+    existingOnly?: boolean;
     /**
      * Repair the two files a previous setup wrote in this repository, and do
      * nothing else. No pairing, no enrollment, no credential, no network: a
@@ -21,6 +27,29 @@ export type SetupOptions = Readonly<{
      * reach the control plane at that moment.
      */
     refresh?: boolean;
+    /**
+     * Set up even though an earlier Balladeer is still installed on this machine.
+     *
+     * The check that stops this run is a warning about two programs claiming one
+     * name, not a safety property, so somebody who has decided to run both says so
+     * and this run carries on exactly as it would have.
+     */
+    force?: boolean;
+    /**
+     * Whether to also connect Claude desktop chat for this repository.
+     *
+     * Three states, because there are three answers and only two of them are a
+     * flag. `true` is `--claude-desktop`: connect it, and say out loud when this
+     * machine has no such app rather than skipping in silence. `false` is
+     * `--no-claude-desktop`: do not touch that file and do not mention it.
+     * Undefined is the ordinary run, which connects it where Claude desktop is
+     * installed and says nothing at all where it is not. Writing it by default is
+     * the same bargain `.mcp.json` already makes: the entry is additive, it
+     * carries no credential, it never replaces anybody else's server, and the
+     * people this is for write their plan in that chat before they open a coding
+     * agent at all.
+     */
+    claudeDesktop?: boolean;
     environment: NodeJS.ProcessEnv;
     cwd: string;
     write: (text: string) => void;