@synap-core/cli 1.10.0 → 1.12.2

package/dist/lib/capture-structure.js

@@ -0,0 +1,295 @@
+/**
+ * Shared shapes + honest reporting for the smart-capture pipeline
+ * (POST /capture/structure → POST /capture/execute).
+ *
+ * ONE declaration of the structure/execute wire shapes and ONE degraded/execute
+ * interpreter, imported by BOTH surfaces that drive this pipeline:
+ *   • `synap capture "<free text>"`  (commands/knowledge.ts)
+ *   • `synap import <files|urls>`    (commands/import.ts)
+ *
+ * These two used to keep independent `StructureResult` copies that had already
+ * drifted (import dropped fields knowledge kept). Consolidating here removes the
+ * drift AND the false-success reporting: the CLI now reports what /capture/execute
+ * ACTUALLY returned (applied vs proposed vs nothing-created) instead of guessing
+ * off the planned proposal count.
+ *
+ * Kept local to the CLI (not imported from @synap-core/hub-rest-client) because the
+ * CLI resolves the SDK via its built dist — the same reason the previous local
+ * mirrors existed. This is now the ONE mirror instead of two.
+ */
+/**
+ * ADVISORY hints only — an AI pick proposes, it never places data. A user's
+ * deliberate choice (`--workspace` / `--project`) is NOT a hint.
+ */
+export function captureExecuteRoutingHints(structured) {
+    return {
+        aiWorkspaceId: structured.targetWorkspaceId,
+        aiWorkspaceConfidence: structured.targetWorkspaceConfidence,
+        aiWorkspaceReason: structured.targetWorkspaceReason,
+        aiWorkspaceDecision: structured.targetWorkspaceDecision,
+        aiProjectId: structured.targetProjectId,
+        aiProjectConfidence: structured.targetProjectConfidence,
+        aiProjectReason: structured.targetProjectReason,
+    };
+}
+/** The AI's workspace-side hints only (drop them when the user pinned a workspace). */
+export function workspaceRoutingHints(structured) {
+    const { aiWorkspaceId, aiWorkspaceConfidence, aiWorkspaceReason, aiWorkspaceDecision } = captureExecuteRoutingHints(structured);
+    return { aiWorkspaceId, aiWorkspaceConfidence, aiWorkspaceReason, aiWorkspaceDecision };
+}
+/** The AI's project-side hints only (drop them when the user pinned a project). */
+export function projectRoutingHints(structured) {
+    const { aiProjectId, aiProjectConfidence, aiProjectReason } = captureExecuteRoutingHints(structured);
+    return { aiProjectId, aiProjectConfidence, aiProjectReason };
+}
+/** THE destination rule — see the shared type's docblock. */
+export function deriveWorkspacePlacementView(placement, selection, opts) {
+    if (!placement) {
+        return {
+            destination: { workspaceId: null, workspaceName: null },
+            aiSuggested: false,
+            alternatives: [],
+            canRemove: false,
+            execute: {},
+        };
+    }
+    const suggestion = placement.suggestion;
+    const base = {
+        workspaceId: placement.workspaceId,
+        workspaceName: placement.workspaceName,
+    };
+    const pinBase = () => placement.deterministic && placement.workspaceId
+        ? { targetWorkspaceId: placement.workspaceId }
+        : {};
+    if (selection.kind === "chosen") {
+        return {
+            destination: {
+                workspaceId: selection.workspaceId,
+                workspaceName: selection.workspaceName,
+            },
+            aiSuggested: false,
+            alternatives: suggestion?.alternatives ?? [],
+            canRemove: false,
+            execute: {
+                targetWorkspaceId: selection.workspaceId,
+                ...(suggestion
+                    ? {
+                        workspaceChoice: selection.workspaceId === suggestion.workspaceId ? "accepted" : "changed",
+                    }
+                    : {}),
+            },
+        };
+    }
+    if (selection.kind === "removed" || !suggestion || !opts.interactive) {
+        const choice = !suggestion
+            ? undefined
+            : selection.kind === "removed"
+                ? "removed"
+                : "ignored";
+        return {
+            destination: base,
+            aiSuggested: false,
+            alternatives: suggestion?.alternatives ?? [],
+            canRemove: false,
+            execute: {
+                ...(choice === "removed" && placement.workspaceId
+                    ? { targetWorkspaceId: placement.workspaceId }
+                    : pinBase()),
+                ...(choice ? { workspaceChoice: choice } : {}),
+            },
+        };
+    }
+    return {
+        destination: {
+            workspaceId: suggestion.workspaceId,
+            workspaceName: suggestion.workspaceName,
+        },
+        aiSuggested: true,
+        alternatives: suggestion.alternatives,
+        canRemove: true,
+        execute: { targetWorkspaceId: suggestion.workspaceId, workspaceChoice: "accepted" },
+    };
+}
+/**
+ * The headless placement fields the CLI sends to `/capture/execute` — the ONE
+ * door, so the CLI can never hand-roll a destination. Headless ⇒ an AI
+ * suggestion stays a proposal; a deterministic placement is pinned explicitly.
+ */
+export function headlessPlacementFields(structured) {
+    return deriveWorkspacePlacementView(structured.placement, { kind: "default" }, {
+        interactive: false,
+    }).execute;
+}
+/**
+ * The workspace line for a structure result: the NAME the pod resolved (never
+ * a raw id when a name is known) and the confidence percent, once.
+ */
+export function formatWorkspaceRouting(result) {
+    const label = result.targetWorkspaceName || result.targetWorkspaceId;
+    if (!label)
+        return null;
+    const conf = typeof result.targetWorkspaceConfidence === "number"
+        ? ` (${Math.round(result.targetWorkspaceConfidence * 100)}%)`
+        : "";
+    return `${label}${conf}`;
+}
+/**
+ * Interpret a /capture/execute response HONESTLY. Distinguishes applied vs
+ * proposed vs nothing-created and surfaces the real proposal/review handle so
+ * the CLI never claims "created" for a write that was proposed or a plan that
+ * only linked existing entities.
+ */
+export function readCaptureExecute(res) {
+    const created = Array.isArray(res.created) ? res.created : [];
+    const proposed = res.status === "proposed" || Boolean(res.proposalId);
+    return {
+        proposed,
+        entitiesCreated: created.filter((c) => !c.linked).length,
+        entitiesLinked: created.filter((c) => c.linked).length,
+        relationsCreated: Array.isArray(res.relations) ? res.relations.length : 0,
+        proposalId: res.proposalId ? String(res.proposalId) : undefined,
+        reviewUrl: res.reviewUrl ? String(res.reviewUrl) : undefined,
+        ...(res.pendingWorkspaceSwitch?.suggestedWorkspaceId
+            ? { pendingWorkspaceSwitch: res.pendingWorkspaceSwitch }
+            : {}),
+    };
+}
+/**
+ * The one line every CLI surface prints for an outstanding workspace
+ * suggestion. It says what to DO (re-file with `--workspace`), because the pod
+ * moved nothing — the old "→ filed into workspace X" line reported a move that
+ * never happened.
+ */
+export function formatPendingWorkspaceSwitch(outcome) {
+    const s = outcome.pendingWorkspaceSwitch;
+    if (!s)
+        return null;
+    const label = s.suggestedWorkspaceName || s.suggestedWorkspaceId;
+    const conf = typeof s.confidence === "number" ? ` (${Math.round(s.confidence * 100)}%)` : "";
+    return `AI suggests workspace ${label}${conf} — nothing was moved. Re-file with --workspace ${s.suggestedWorkspaceId} to accept.`;
+}
+/** True when the structure step degraded (nothing usable came back). */
+export function isDegraded(res) {
+    return res.degraded === true;
+}
+/**
+ * One line of honest copy for a degraded reason: WHAT happened, and WHAT TO DO.
+ *
+ * ── Why this is a second table, deliberately ────────────────────────────────
+ * `@synap-core/capture-pipeline`'s `describeDegradedReason` is the existing
+ * one-door for this copy, and it is the RIGHT door — but the CLI is a separate
+ * pnpm workspace whose only Synap runtime dependencies are
+ * `@synap-core/hub-rest-client` (a file: link into synap-backend) and
+ * `@synap-core/workspace-templates`. It cannot reach a `synap-app` package
+ * without a package.json/lockfile change. Same reason the `StructureResult`
+ * mirror above is local.
+ *
+ * So: the `title` half is COPIED VERBATIM from `describeDegradedReason` and
+ * pinned by a parity test (`test/degraded-message-honesty.test.ts`) that reads
+ * the sibling repo's source, so the two can never drift on WHAT happened.
+ * The `detail` half is deliberately DIFFERENT, because the app's
+ * details end in "saved as a note in the meantime" and the CLI creates nothing
+ * at all — repeating the app's sentence here would be a new lie in place of the
+ * old one.
+ */
+export function describeDegradedReason(reason) {
+    switch (reason) {
+        case "is_auth_error":
+            return {
+                title: "AI intelligence isn't connected",
+                detail: "This pod's Intelligence Service rejected its credentials. Check them with `synap doctor`, then re-run this import.",
+            };
+        case "llm_budget_exceeded":
+            return {
+                title: "The monthly AI budget is used up",
+                detail: "The Intelligence Service's monthly token budget is spent, so nothing was created. Re-run this import once the budget resets next month or an operator raises it.",
+            };
+        case "pdf_scanned_needs_ocr":
+            return {
+                title: "This PDF has no text layer",
+                detail: "It's a scan, not typed text, so there is nothing to read yet. OCR it first, or keep the original with `synap import --keep-raw <file>`.",
+            };
+        case "pdf_missing_binary":
+            return {
+                title: "The PDF file wasn't available to read",
+                detail: "The bytes never reached the pod. Re-run the import for this file.",
+            };
+        case "vision_provider_not_configured":
+            return {
+                title: "Image reading isn't set up on this pod",
+                detail: "No vision-capable model is configured, so images can't be described. Configure one in Settings → Intelligence; until then keep the original with `synap import --keep-raw <file>`.",
+            };
+        case "vision_provider_failed":
+            return {
+                title: "Couldn't reach the AI that reads images",
+                detail: "A vision model is configured but the call failed (an outage, an unfunded key or an unknown model). Re-run this import later; `synap doctor` checks the pod.",
+            };
+        case "image_missing_binary":
+            return {
+                title: "The image file wasn't available to read",
+                detail: "The bytes never reached the pod. Re-run the import for this file.",
+            };
+        case "transcription_provider_not_configured":
+            return {
+                title: "Audio transcription isn't set up on this pod",
+                detail: "No transcription model is configured, so speech can't be turned into text. Configure one in Settings → Intelligence; until then keep the original with `synap import --keep-raw <file>`.",
+            };
+        case "audio_missing_binary":
+            return {
+                title: "The audio file wasn't available to read",
+                detail: "The bytes never reached the pod. Re-run the import for this file.",
+            };
+        case "docx_missing_binary":
+            return {
+                title: "The document file wasn't available to read",
+                detail: "The bytes never reached the pod. Re-run the import for this file.",
+            };
+        case "docx_empty":
+            return {
+                title: "This document has no extractable text",
+                detail: "It parsed cleanly but came back empty. Keep the original with `synap import --keep-raw <file>` if you still want it stored.",
+            };
+        case "html_empty":
+            return {
+                title: "This page has no extractable text",
+                detail: "It parsed cleanly but came back empty — often a JavaScript-rendered page. Save the readable text yourself and pass it to `synap capture`.",
+            };
+        case "unsupported_type":
+            return {
+                title: "This file type isn't supported yet",
+                detail: "Nothing can be extracted from it. Keep the bytes anyway with `synap import --keep-raw <file>`, or `synap upload <file>` to store it as a file entity.",
+            };
+        case "is_invalid_response":
+        case "is_empty_result":
+        case undefined:
+            return {
+                title: "AI structuring is unavailable right now",
+                detail: "Nothing was created. Re-run this import when the structurer is back.",
+            };
+        default:
+            // A reason this list hasn't been taught yet (the IS added one, and the
+            // wire type is an open string). Degrade gracefully — never print the raw
+            // token at a user, and never crash on it.
+            return {
+                title: "This input couldn't be read",
+                detail: "Nothing was created. Run `synap doctor` to check what this pod can extract.",
+            };
+    }
+}
+/**
+ * The ONE degraded message. The CLI does NOT materialize the server's generic
+ * `item` stand-in (the browser does the same via `offlineFallback:false`), so a
+ * captured note is never silently downgraded to an unstructured blob behind a
+ * "success" line.
+ *
+ * It used to print a single sentence for every cause — "AI structuring
+ * unavailable (is_empty_result) — nothing was created. Retry when it's back."
+ * — which leaked a raw machine token AND told users to retry states that never
+ * change (a pod with no vision provider is not going to come back). Now each
+ * reason says what actually happened and what to do about it.
+ */
+export function degradedMessage(res) {
+    const { title, detail } = describeDegradedReason(res.degradedReason);
+    return `${title} — nothing was created. ${detail}`;
+}
+//# sourceMappingURL=capture-structure.js.map

package/dist/lib/capture-structure.js.map

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

package/dist/lib/catalog-templates.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Where `synap bridge setup` reads the agency skills and the bridge automations.
+ *
+ * Their home is the catalog package (`@synap-core/catalog`, or
+ * `@synap-core/workspace-templates` before the rename): `skills/<name>/SKILL.md`
+ * and `automations/*.automation.json`. The CLI keeps copies under `templates/`
+ * for installs whose catalog package does not ship them yet. Resolution is per
+ * item: the INSTALLED package wins when it ships the item, the CLI copy is the
+ * fallback. The runtime skills (`authoring-*`, `coordinating-*`) have no catalog
+ * copy and always come from the CLI.
+ *
+ * Retirement: once the installed package ships an item, its CLI copy is dead
+ * weight that can silently fork. `catalogRetirementViolations` names those
+ * copies; `test/catalog-templates.test.ts` fails on any, so the pin bump that
+ * brings them in also deletes the CLI copies.
+ */
+/** Package names the catalog may be installed under (new name first). */
+export declare const CATALOG_TEMPLATE_PACKAGES: readonly ["@synap-core/catalog", "@synap-core/workspace-templates"];
+/**
+ * The agency/domain skills whose home is the catalog. Every other bundled skill
+ * is a CLI runtime skill. Pinned (not derived from the catalog) so the set
+ * bridge-setup seeds does not grow because the catalog gained a skill.
+ */
+export declare const AGENCY_SKILLS: readonly ["bookmark-enrichment", "mapping-the-server", "reading-client-progress", "routing-to-channels", "stellar-scf-grants-advisor"];
+/** `<cli package root>/templates` (same depth from `src/lib` and `dist/lib`). */
+export declare const CLI_TEMPLATES_DIR: string;
+/**
+ * Root directory of the installed catalog package, or null when none resolves.
+ * Resolves the package's entry point and walks up to its package.json, because
+ * older versions do not export `./package.json`.
+ */
+export declare function resolveInstalledCatalogRoot(resolve?: (id: string) => string): string | null;
+/**
+ * The SKILL.md directories bridge-setup seeds: each agency skill from the
+ * installed catalog when it ships it, else from the CLI; plus every CLI runtime
+ * skill. `fromCatalog` names the skills read from the catalog.
+ */
+export declare function resolveAgencySkillDirs(opts: {
+    cliSkillsDir: string | null;
+    catalogRoot: string | null;
+}): {
+    dirs: string[];
+    fromCatalog: string[];
+};
+/**
+ * The automation templates directory: the `override` (AUTOMATION_TEMPLATES_DIR)
+ * when set (null if it does not exist), else the installed catalog's
+ * `automations/` when it ships any `*.automation.json`, else the CLI copy.
+ */
+export declare function resolveAutomationTemplatesDir(opts: {
+    override?: string;
+    catalogRoot: string | null;
+    cliDir: string;
+}): string | null;
+/**
+ * CLI copies the installed catalog makes redundant, as paths relative to the CLI
+ * package root (`templates/skills/<name>`, `templates/automations/<file>`).
+ */
+export declare function catalogRetirementViolations(catalogRoot: string | null, cliTemplatesDir: string): string[];

package/dist/lib/catalog-templates.js

@@ -0,0 +1,126 @@
+/**
+ * Where `synap bridge setup` reads the agency skills and the bridge automations.
+ *
+ * Their home is the catalog package (`@synap-core/catalog`, or
+ * `@synap-core/workspace-templates` before the rename): `skills/<name>/SKILL.md`
+ * and `automations/*.automation.json`. The CLI keeps copies under `templates/`
+ * for installs whose catalog package does not ship them yet. Resolution is per
+ * item: the INSTALLED package wins when it ships the item, the CLI copy is the
+ * fallback. The runtime skills (`authoring-*`, `coordinating-*`) have no catalog
+ * copy and always come from the CLI.
+ *
+ * Retirement: once the installed package ships an item, its CLI copy is dead
+ * weight that can silently fork. `catalogRetirementViolations` names those
+ * copies; `test/catalog-templates.test.ts` fails on any, so the pin bump that
+ * brings them in also deletes the CLI copies.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { discoverSkillDirs } from "./skill-import.js";
+/** Package names the catalog may be installed under (new name first). */
+export const CATALOG_TEMPLATE_PACKAGES = ["@synap-core/catalog", "@synap-core/workspace-templates"];
+/**
+ * The agency/domain skills whose home is the catalog. Every other bundled skill
+ * is a CLI runtime skill. Pinned (not derived from the catalog) so the set
+ * bridge-setup seeds does not grow because the catalog gained a skill.
+ */
+export const AGENCY_SKILLS = [
+    "bookmark-enrichment",
+    "mapping-the-server",
+    "reading-client-progress",
+    "routing-to-channels",
+    "stellar-scf-grants-advisor",
+];
+/** `<cli package root>/templates` (same depth from `src/lib` and `dist/lib`). */
+export const CLI_TEMPLATES_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "templates");
+/**
+ * Root directory of the installed catalog package, or null when none resolves.
+ * Resolves the package's entry point and walks up to its package.json, because
+ * older versions do not export `./package.json`.
+ */
+export function resolveInstalledCatalogRoot(resolve = createRequire(import.meta.url).resolve) {
+    for (const name of CATALOG_TEMPLATE_PACKAGES) {
+        let entry;
+        try {
+            entry = resolve(name);
+        }
+        catch {
+            continue; // not installed under this name
+        }
+        for (let dir = path.dirname(entry); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+            const pj = path.join(dir, "package.json");
+            if (!fs.existsSync(pj))
+                continue;
+            if (JSON.parse(fs.readFileSync(pj, "utf8")).name === name)
+                return dir;
+        }
+    }
+    return null;
+}
+function catalogSkillDir(catalogRoot, name) {
+    if (!catalogRoot)
+        return null;
+    const dir = path.join(catalogRoot, "skills", name);
+    return fs.existsSync(path.join(dir, "SKILL.md")) ? dir : null;
+}
+function catalogAutomationFiles(catalogRoot) {
+    const dir = catalogRoot ? path.join(catalogRoot, "automations") : null;
+    if (!dir || !fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir).filter((f) => f.endsWith(".automation.json"));
+}
+/**
+ * The SKILL.md directories bridge-setup seeds: each agency skill from the
+ * installed catalog when it ships it, else from the CLI; plus every CLI runtime
+ * skill. `fromCatalog` names the skills read from the catalog.
+ */
+export function resolveAgencySkillDirs(opts) {
+    const agency = new Set(AGENCY_SKILLS);
+    const dirs = [];
+    const fromCatalog = [];
+    const cliDirs = opts.cliSkillsDir ? discoverSkillDirs(opts.cliSkillsDir) : [];
+    for (const cliDir of cliDirs)
+        if (!agency.has(path.basename(cliDir)))
+            dirs.push(cliDir);
+    for (const name of AGENCY_SKILLS) {
+        const fromPkg = catalogSkillDir(opts.catalogRoot, name);
+        if (fromPkg) {
+            dirs.push(fromPkg);
+            fromCatalog.push(name);
+            continue;
+        }
+        const cliDir = cliDirs.find((d) => path.basename(d) === name);
+        if (cliDir)
+            dirs.push(cliDir);
+    }
+    return { dirs, fromCatalog };
+}
+/**
+ * The automation templates directory: the `override` (AUTOMATION_TEMPLATES_DIR)
+ * when set (null if it does not exist), else the installed catalog's
+ * `automations/` when it ships any `*.automation.json`, else the CLI copy.
+ */
+export function resolveAutomationTemplatesDir(opts) {
+    if (opts.override)
+        return fs.existsSync(opts.override) ? opts.override : null;
+    if (opts.catalogRoot && catalogAutomationFiles(opts.catalogRoot).length > 0)
+        return path.join(opts.catalogRoot, "automations");
+    return fs.existsSync(opts.cliDir) ? opts.cliDir : null;
+}
+/**
+ * CLI copies the installed catalog makes redundant, as paths relative to the CLI
+ * package root (`templates/skills/<name>`, `templates/automations/<file>`).
+ */
+export function catalogRetirementViolations(catalogRoot, cliTemplatesDir) {
+    const out = [];
+    for (const name of AGENCY_SKILLS)
+        if (catalogSkillDir(catalogRoot, name) && fs.existsSync(path.join(cliTemplatesDir, "skills", name)))
+            out.push(`templates/skills/${name}`);
+    for (const file of catalogAutomationFiles(catalogRoot))
+        if (fs.existsSync(path.join(cliTemplatesDir, "automations", file)))
+            out.push(`templates/automations/${file}`);
+    return out;
+}
+//# sourceMappingURL=catalog-templates.js.map

package/dist/lib/catalog-templates.js.map

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

package/dist/lib/cli-build.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which CLI is running: its version AND the commit it was built from.
+ *
+ * The version alone could not tell an Oct-11 test-branch build from current
+ * main (2026-10-15 devbox incident: same version, old code, wrong success
+ * line). `build` stamps `dist/build-info.json` (`scripts/write-build-info.mjs`);
+ * running from source (`tsx`) there is no stamp, and that is said, not hidden.
+ */
+export interface CliBuild {
+    version: string;
+    sha?: string;
+    branch?: string;
+    /** Built with uncommitted changes under src/. */
+    dirty?: boolean;
+    builtAt?: string;
+}
+export declare function cliBuild(dir?: string): CliBuild;
+/** "1.12.0 (a750d09 main, built 2026-10-15)" — the version stays the first word. */
+export declare function formatCliBuild(b: CliBuild): string;

package/dist/lib/cli-build.js

@@ -0,0 +1,37 @@
+/**
+ * Which CLI is running: its version AND the commit it was built from.
+ *
+ * The version alone could not tell an Oct-11 test-branch build from current
+ * main (2026-10-15 devbox incident: same version, old code, wrong success
+ * line). `build` stamps `dist/build-info.json` (`scripts/write-build-info.mjs`);
+ * running from source (`tsx`) there is no stamp, and that is said, not hidden.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// dist/lib/cli-build.js → dist/build-info.json, package.json at the package
+// root; the same two hops from src/lib when running from source.
+const here = path.dirname(fileURLToPath(import.meta.url));
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function cliBuild(dir = here) {
+    const pkg = readJson(path.join(dir, "..", "..", "package.json"));
+    const stamp = readJson(path.join(dir, "..", "build-info.json"));
+    return { version: pkg?.version ?? "unknown", ...(stamp ?? {}) };
+}
+/** "1.12.0 (a750d09 main, built 2026-10-15)" — the version stays the first word. */
+export function formatCliBuild(b) {
+    if (!b.builtAt)
+        return `${b.version} (no build stamp: running from source or an unstamped build)`;
+    const day = b.builtAt.slice(0, 10);
+    if (!b.sha)
+        return `${b.version} (built ${day}, commit unknown)`;
+    return `${b.version} (${b.sha}${b.dirty ? "+changes" : ""}${b.branch ? ` ${b.branch}` : ""}, built ${day})`;
+}
+//# sourceMappingURL=cli-build.js.map

package/dist/lib/cli-build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-build.js","sourceRoot":"","sources":["../../src/lib/cli-build.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAWzC,4EAA4E;AAC5E,iEAAiE;AACjE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,SAAS,QAAQ,CAAI,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAM,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAG,GAAG,IAAI;IACjC,MAAM,GAAG,GAAG,QAAQ,CAAuB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IACvF,MAAM,KAAK,GAAG,QAAQ,CAA4B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC3F,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,SAAS,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,CAAW;IACxC,IAAI,CAAC,CAAC,CAAC,OAAO;QAAE,OAAO,GAAG,CAAC,CAAC,OAAO,8DAA8D,CAAC;IAClG,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC,CAAC,OAAO,WAAW,GAAG,mBAAmB,CAAC;IACjE,OAAO,GAAG,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,GAAG,GAAG,CAAC;AAC9G,CAAC"}

package/dist/lib/conversation-headers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The headers that name the calling CONVERSATION to the pod — the agent's own
+ * id, the one a person can reopen (`claude --resume <id>`). The pod reads
+ * `X-Synap-Conversation` as the conversation half of the client key, so every
+ * session the conversation touches records it (`resolveAgentConversation`,
+ * @synap-core/types/agents). Sent by every Hub call (`hub-client.ts`) and by
+ * the stdio MCP bridge (`mcp-bridge.ts`). Empty outside Claude Code.
+ */
+export declare const CONVERSATION_HEADER = "X-Synap-Conversation";
+export declare const CONVERSATION_CWD_HEADER = "X-Synap-Conversation-Cwd";
+/** `claude-code:<uuid>` for the Claude Code conversation we run in, if any. */
+export declare function claudeCodeConversation(sessionId: string | undefined): string | undefined;
+/**
+ * The headers for `sessionId` (pass it explicitly: the CLI's live id is
+ * `getClaudeSessionId()`, a stdio server's is its spawn env). Empty without a
+ * real Claude Code id; the cwd rides only with a conversation.
+ */
+export declare function conversationHeaders(sessionId: string | undefined, cwd?: string): Record<string, string>;

package/dist/lib/conversation-headers.js

@@ -0,0 +1,32 @@
+/**
+ * The headers that name the calling CONVERSATION to the pod — the agent's own
+ * id, the one a person can reopen (`claude --resume <id>`). The pod reads
+ * `X-Synap-Conversation` as the conversation half of the client key, so every
+ * session the conversation touches records it (`resolveAgentConversation`,
+ * @synap-core/types/agents). Sent by every Hub call (`hub-client.ts`) and by
+ * the stdio MCP bridge (`mcp-bridge.ts`). Empty outside Claude Code.
+ */
+export const CONVERSATION_HEADER = "X-Synap-Conversation";
+export const CONVERSATION_CWD_HEADER = "X-Synap-Conversation-Cwd";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `claude-code:<uuid>` for the Claude Code conversation we run in, if any. */
+export function claudeCodeConversation(sessionId) {
+    const id = sessionId?.trim();
+    return id && UUID.test(id) ? `claude-code:${id.toLowerCase()}` : undefined;
+}
+/**
+ * The headers for `sessionId` (pass it explicitly: the CLI's live id is
+ * `getClaudeSessionId()`, a stdio server's is its spawn env). Empty without a
+ * real Claude Code id; the cwd rides only with a conversation.
+ */
+export function conversationHeaders(sessionId, cwd = process.cwd()) {
+    const conversation = claudeCodeConversation(sessionId);
+    if (!conversation)
+        return {};
+    // HTTP header values must be ByteStrings; a non-ASCII cwd is dropped rather
+    // than letting fetch throw and take the whole request down with it.
+    return /^[\x20-\x7E]{1,1024}$/.test(cwd)
+        ? { [CONVERSATION_HEADER]: conversation, [CONVERSATION_CWD_HEADER]: cwd }
+        : { [CONVERSATION_HEADER]: conversation };
+}
+//# sourceMappingURL=conversation-headers.js.map

package/dist/lib/conversation-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-headers.js","sourceRoot":"","sources":["../../src/lib/conversation-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAAsB,CAAC;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,0BAA0B,CAAC;AAElE,MAAM,IAAI,GAAG,iEAAiE,CAAC;AAE/E,+EAA+E;AAC/E,MAAM,UAAU,sBAAsB,CAAC,SAA6B;IAClE,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC;IAC7B,OAAO,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA6B,EAC7B,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,MAAM,YAAY,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,CAAC,YAAY;QAAE,OAAO,EAAE,CAAC;IAC7B,4EAA4E;IAC5E,oEAAoE;IACpE,OAAO,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC;QACtC,CAAC,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC,uBAAuB,CAAC,EAAE,GAAG,EAAE;QACzE,CAAC,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC;AAC9C,CAAC"}