@consiliency/agent-board-cli 1.24.0 → 1.25.0

package/dist/setup_writers.d.ts

@@ -0,0 +1,128 @@
+import { type IdentityHarness } from "@consiliency/agent-board-client";
+import type { BakedAssets } from "./assets.js";
+import { type ConfigEntry } from "./config_edit.js";
+import { type RegistrationFs, type ScopeContext } from "./doctor_scopes.js";
+export type SetupScope = "user" | "local";
+export declare const SETUP_SCOPES: readonly SetupScope[];
+/** The server name setup writes; the same name the claude plugin registers. */
+export declare const BOARD_SERVER_NAME = "agent-board";
+/** `Consiliency/message-board`: the marketplace source, pinned to the baked release tag. */
+export declare const CLAUDE_MARKETPLACE_REPO = "Consiliency/message-board";
+/**
+ * What codex hands an MCP child and nothing else (`process_ancestry.ts`, measured 2026-09-18 on
+ * codex 0.155.0, across three configurations including `shell_environment_policy.inherit=all`).
+ * The writer test pins this list against that measurement's own text.
+ */
+export declare const CODEX_CHILD_ENV: readonly ["HOME", "LANG", "LOGNAME", "PATH", "SHELL", "TERM", "USER"];
+/**
+ * Every non-secret input that decides where the identity file and the runtime records resolve
+ * (`identityConfigRoot`, `identityStateRoot`, `resolveHostSegment`). Written into the codex
+ * stanza's `env` when setup's own value is not the default, so the child resolves what setup
+ * wrote. Never a credential: the identity itself comes from the file.
+ */
+export declare const CODEX_PATH_INPUTS: readonly ["XDG_CONFIG_HOME", "XDG_STATE_HOME", "MESSAGE_BOARD_WAKE_MACHINE_ID", "MESSAGE_BOARD_WAKE_HOSTNAME"];
+/** `secret-tool` inherits the child env (`keystore_os_keychain.ts`): an os_keychain key needs the session bus. */
+export declare const KEYCHAIN_CHILD_INPUTS: readonly ["DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR"];
+export interface McpStanza extends ConfigEntry {
+    command: string;
+    args: string[];
+}
+/**
+ * The env an `agent_socket:` reference's socket resolves through, which codex does not hand its
+ * child: `MESSAGE_BOARD_AGENT_SOCKET_PATH` when setup's env sets it (it overrides the handle), else
+ * `SSH_AUTH_SOCK` when the handle names the socket only by that sentinel (an external agent). An
+ * absolute socket in the handle (a keyslot) needs nothing. null: the socket resolves to nothing
+ * here, so no child could reach it.
+ */
+export declare function agentSocketInputs(keyReference: string | null, env: NodeJS.ProcessEnv): Record<string, string> | null;
+/**
+ * The codex stanza's `env`: each frozen path input setup's env sets to a non-default value, the
+ * session bus for an os_keychain key, and the socket inputs of an agent_socket one. null when the
+ * key's socket cannot be resolved (see `agentSocketInputs`).
+ */
+export declare function codexStanzaEnv(env: NodeJS.ProcessEnv, keyReference: string | null): Record<string, string> | null;
+/** The environment codex actually gives the MCP child: the frozen seven from `env`, then the stanza's. */
+export declare function codexChildEnv(env: NodeJS.ProcessEnv, stanza: ConfigEntry): NodeJS.ProcessEnv;
+/**
+ * The stanza setup writes for an MCP-configured harness: `npx -y <mcp>@<pin> --harness <h>` (+ the
+ * codex env). null only for codex, when its key's agent socket resolves to nothing here.
+ */
+export declare function mcpStanza(harness: IdentityHarness, assets: BakedAssets, env: NodeJS.ProcessEnv, keyReference: string | null): McpStanza | null;
+/**
+ * Whether an entry under our name runs OUR server: an argv element whose package identity is
+ * exactly `@consiliency/agent-board-mcp` (any version, as `npx -y <pkg>@<v>` passes it), or the
+ * package's bin `agent-board-mcp` as its own element. A substring is never enough: a lookalike
+ * package (`@example/agent-board-mcp-tools`, `@consiliency/agent-board-mcp-extra`) or a wrapper
+ * script whose path merely contains the name is someone else's, and is never overwritten.
+ */
+export declare function isOurServer(words: readonly string[]): boolean;
+/**
+ * The `env` names setup owns: exactly the ones it may write. Any other name a user keeps in the
+ * entry's `env` survives an upgrade; an owned one setup no longer writes is dropped.
+ */
+export declare const OWNED_ENV_NAMES: ReadonlySet<string>;
+export interface Refusal {
+    reason: string;
+    fix: string;
+}
+/**
+ * Whether `setup --harness <h> --scope <s>` is supported here. agy has no project scope; a codex
+ * project layer is loaded only under a trusted `[projects]` entry, judged by doctor's own walk
+ * (the `codex_project` row's `loaded`), so setup and doctor cannot disagree. Setup never writes trust.
+ */
+export declare function scopeRefusal(harness: IdentityHarness, scope: SetupScope, ctx: {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    fs?: RegistrationFs;
+    claudeManagedDir?: string;
+}): Refusal | null;
+export interface ChildOutcome {
+    /** null when the child did not exit on its own (not spawned, killed, timed out). */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Runs a child with NO stdin (`/dev/null`); stdout and stderr are captured, never inherited. */
+export type ChildRunner = (file: string, args: readonly string[], options: {
+    env: NodeJS.ProcessEnv;
+    cwd?: string;
+    timeoutMs?: number;
+}) => Promise<ChildOutcome>;
+export declare const defaultChildRunner: ChildRunner;
+/** An executable named `name` on `env`'s PATH (never `process.env`'s), or null. */
+export declare function which(name: string, env: NodeJS.ProcessEnv): string | null;
+export interface WriterContext {
+    harness: IdentityHarness;
+    scope: SetupScope;
+    assets: BakedAssets;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    /** The identity's key reference, read from the identity file (never from a setup record). */
+    keyReference: string | null;
+    followSymlinks: boolean;
+    run?: ChildRunner;
+    fs?: RegistrationFs;
+    claudeManagedDir?: string;
+}
+export interface WriterResult {
+    status: "done" | "already" | "failed";
+    reason: string;
+    fix?: string;
+}
+/** The MCP-writer target file for a harness and scope, as doctor's scope rows locate it. */
+export declare function mcpTarget(harness: IdentityHarness, scope: SetupScope, ctx: ScopeContext): string;
+/**
+ * Setup's exact check for claude: our plugin, at the baked version, from the baked release tag,
+ * effective here AND installed and enabled at the REQUESTED scope from that tag.
+ */
+export declare function claudePluginExact(ctx: ScopeContext, assets: BakedAssets, scope: SetupScope): {
+    exact: boolean;
+    installedAtScope: boolean;
+    enabledAtScope: boolean;
+    disabledAtScope: boolean;
+    pinnedAtScope: boolean;
+    foreign: boolean;
+    unparseable: boolean;
+};
+/** The `harness` step for one harness and scope. Never throws for a host condition. */
+export declare function installHarness(ctx: WriterContext): Promise<WriterResult>;