backpack-ontology 0.7.6 → 0.7.8

package/dist/mcp/tools/signal-tools.js

@@ -0,0 +1,295 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { z } from "zod";
+import { trackEvent } from "../../core/telemetry.js";
+import { dataDir } from "../../core/paths.js";
+export function registerSignalTools(server, backpack) {
+    server.registerTool("backpack_signal_list", {
+        title: "List Signals",
+        description: "List active signals for the current backpack. Signals are derived insights — concentration risks, bridge nodes, orphan clusters, cross-graph entities — computed from graph structure and KB content. Filter by graph, kind, severity, or text search. Search 'chester' to find signals touching Chester across all graphs.",
+        inputSchema: {
+            graph: z.string().optional().describe("Filter to signals involving this graph"),
+            kind: z.string().optional().describe("Filter by signal kind (e.g. 'concentration_risk', 'bridge_node', 'cross_graph_entity')"),
+            severity: z.string().optional().describe("Filter by severity: 'critical', 'high', 'medium', 'low'"),
+            query: z.string().optional().describe("Text search across signal titles, descriptions, and graph names"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ graph, kind, severity, query }) => {
+        try {
+            const store = await backpack.signals();
+            const result = await store.list({
+                graph,
+                kind: kind,
+                severity,
+                query,
+            });
+            trackEvent("tool_call", { tool: "backpack_signal_list" });
+            if (result.signals.length === 0) {
+                const msg = result.computedAt
+                    ? `No active signals${graph ? ` for "${graph}"` : ""}${query ? ` matching "${query}"` : ""}. ${result.dismissed} dismissed. Last detected: ${result.computedAt}`
+                    : "No signals detected yet. Run backpack_signal_detect to scan the backpack.";
+                return { content: [{ type: "text", text: msg }] };
+            }
+            const lines = result.signals.map((s) => {
+                const graphs = s.graphNames.join(", ");
+                return `[${s.severity.toUpperCase()}] ${s.title}\n  Kind: ${s.kind} | Graphs: ${graphs} | Score: ${s.score.toFixed(1)}\n  Evidence nodes: ${s.evidenceNodeIds.slice(0, 5).join(", ")}${s.evidenceNodeIds.length > 5 ? "…" : ""}\n  ID: ${s.id}`;
+            });
+            const header = `${result.signals.length} active signal${result.signals.length > 1 ? "s" : ""}${result.dismissed ? ` (${result.dismissed} dismissed)` : ""} — last detected ${result.computedAt}`;
+            return {
+                content: [{ type: "text", text: `${header}\n\n${lines.join("\n\n")}` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("backpack_signal_detect", {
+        title: "Detect Signals",
+        description: "Scan ALL graphs and KB documents in the active backpack to detect signals. Runs structural detectors (concentration risk, bridge nodes, orphan clusters, stale clusters, sparse types) and cross-cutting detectors (cross-graph entities, type overlap). Results are persisted to signals.json. Run this after mining, adding nodes, or writing KB docs.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const store = await backpack.signals();
+            // Load all graphs
+            const summaries = await backpack.listOntologies();
+            const graphs = [];
+            for (const s of summaries) {
+                try {
+                    const data = await backpack.loadOntology(s.name);
+                    graphs.push({ name: s.name, data });
+                }
+                catch {
+                    // skip graphs that fail to load
+                }
+            }
+            // Load KB doc metadata
+            let docs = [];
+            try {
+                const docStore = await backpack.documents();
+                const result = await docStore.list({ limit: 500 });
+                docs = result.documents;
+            }
+            catch {
+                // KB might not be configured
+            }
+            const result = await store.detect(graphs, docs);
+            trackEvent("tool_call", { tool: "backpack_signal_detect" });
+            if (result.signals.length === 0) {
+                return {
+                    content: [{ type: "text", text: `Detection complete. No signals found across ${graphs.length} graph${graphs.length !== 1 ? "s" : ""} and ${docs.length} KB doc${docs.length !== 1 ? "s" : ""}. ${result.dismissed} previously dismissed.` }],
+                };
+            }
+            const bySeverity = {};
+            for (const s of result.signals)
+                bySeverity[s.severity] = (bySeverity[s.severity] ?? 0) + 1;
+            const summary = Object.entries(bySeverity)
+                .filter(([, count]) => count > 0)
+                .map(([sev, count]) => `${count} ${sev}`)
+                .join(", ");
+            // Build node label lookup for evidence context
+            const nodeLabels = new Map();
+            for (const { data } of graphs) {
+                for (const node of data.nodes) {
+                    const label = Object.values(node.properties).find((v) => typeof v === "string" && v.length > 0) ?? node.id;
+                    const propSummary = Object.entries(node.properties)
+                        .filter(([, v]) => v !== undefined && v !== null && String(v).length < 80)
+                        .slice(0, 3)
+                        .map(([k, v]) => `${k}: ${v}`)
+                        .join(", ");
+                    nodeLabels.set(node.id, { label, type: node.type, props: propSummary });
+                }
+            }
+            // Output top signals with full evidence context for LLM enrichment
+            const topSignals = result.signals.slice(0, 15);
+            const signalBlocks = topSignals.map((s, i) => {
+                const evidenceContext = s.evidenceNodeIds.slice(0, 5).map((nid) => {
+                    const info = nodeLabels.get(nid);
+                    return info ? `  - "${info.label}" (${info.type}${info.props ? `: ${info.props}` : ""})` : `  - ${nid}`;
+                }).join("\n");
+                return `${i + 1}. [${s.severity.toUpperCase()}] ${s.title}\n   Kind: ${s.kind} | Graphs: ${s.graphNames.join(", ")}\n   Description: ${s.description}\n   Evidence nodes:\n${evidenceContext || "   (none)"}`;
+            });
+            const more = result.signals.length > 15
+                ? `\n\n… and ${result.signals.length - 15} more (use backpack_signal_list to see all)`
+                : "";
+            const enrichmentPrompt = `\n\n---\nYou now have ${result.signals.length} signals with evidence context. For the HIGH and MEDIUM signals above, write a brief enrichment — 1-2 sentences explaining WHY this signal matters in the context of this specific backpack and what the user should consider doing about it. Use the evidence node labels and properties to make it specific, not generic. Then save the enriched descriptions back to the signals using backpack_signal_list to review.`;
+            return {
+                content: [{
+                        type: "text",
+                        text: `Detected ${result.signals.length} signal${result.signals.length > 1 ? "s" : ""} across ${graphs.length} graph${graphs.length !== 1 ? "s" : ""} (${summary})${result.dismissed ? ` — ${result.dismissed} dismissed` : ""}:\n\n${signalBlocks.join("\n\n")}${more}${enrichmentPrompt}`,
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("backpack_signal_dismiss", {
+        title: "Dismiss Signal",
+        description: "Dismiss a signal by ID. Dismissed signals won't appear in signal_list until the backpack state changes enough to produce a different signal at that location. Use this to acknowledge a signal you've seen and don't need surfaced anymore.",
+        inputSchema: {
+            signalId: z.string().describe("ID of the signal to dismiss"),
+        },
+    }, async ({ signalId }) => {
+        try {
+            const store = await backpack.signals();
+            await store.dismiss(signalId);
+            trackEvent("tool_call", { tool: "backpack_signal_dismiss" });
+            return {
+                content: [{ type: "text", text: `Signal "${signalId}" dismissed.` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("backpack_signal_configure", {
+        title: "Configure Signals",
+        description: "Adjust signal detection sensitivity and enable/disable specific detector kinds. Sensitivity is 0.0–1.0: lower values surface fewer, higher-confidence signals; higher values surface more signals including lower-confidence ones. Default is 0.5.",
+        inputSchema: {
+            sensitivity: z.number().min(0).max(1).optional().describe("Detection sensitivity (0.0 = only critical, 1.0 = everything). Default 0.5."),
+            disabledKinds: z.array(z.string()).optional().describe("Signal kinds to disable (e.g. ['sparse_type', 'stale_cluster'])"),
+        },
+    }, async ({ sensitivity, disabledKinds }) => {
+        try {
+            const store = await backpack.signals();
+            const config = await store.configure({
+                sensitivity,
+                disabledKinds: disabledKinds,
+            });
+            trackEvent("tool_call", { tool: "backpack_signal_configure" });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Signal config updated:\n  Sensitivity: ${config.sensitivity}\n  Disabled kinds: ${config.disabledKinds.length > 0 ? config.disabledKinds.join(", ") : "(none)"}`,
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("backpack_signal_enrich", {
+        title: "Enrich Signal Descriptions",
+        description: "Update signal descriptions with LLM-enriched contextual explanations. After running signal_detect, use this to rewrite signal descriptions with richer context that explains WHY the signal matters and what to do about it. Pass an array of {id, description} pairs.",
+        inputSchema: {
+            enrichments: z.array(z.object({
+                id: z.string().describe("Signal ID"),
+                description: z.string().describe("Enriched description with contextual explanation"),
+            })).describe("Array of signal ID + enriched description pairs"),
+        },
+    }, async ({ enrichments }) => {
+        try {
+            const store = await backpack.signals();
+            const file = await store.load();
+            let updated = 0;
+            for (const { id, description } of enrichments) {
+                const signal = file.signals.find((s) => s.id === id);
+                if (signal) {
+                    signal.description = description;
+                    updated++;
+                }
+            }
+            if (updated > 0) {
+                await store.save(file);
+            }
+            trackEvent("tool_call", { tool: "backpack_signal_enrich" });
+            return {
+                content: [{ type: "text", text: `Enriched ${updated} signal description${updated !== 1 ? "s" : ""}.` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("backpack_signal_selected", {
+        title: "Get Selected Signals",
+        description: "Read the signals the user has selected in the viewer. Returns the full signal data with evidence context for each checked signal. Use this when the user says 'look at my selected signals', 'enrich these', 'mine these signals', or 'write a KB for these signals'.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        try {
+            // Read viewer state to get selected signal IDs
+            const statePath = path.join(dataDir(), "viewer-state.json");
+            let selectedIds = [];
+            try {
+                const raw = await fs.readFile(statePath, "utf8");
+                const state = JSON.parse(raw);
+                selectedIds = state.selectedSignalIds ?? [];
+            }
+            catch {
+                return {
+                    content: [{ type: "text", text: "No viewer state available — the viewer may not be running, or no signals are selected." }],
+                };
+            }
+            if (selectedIds.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No signals selected. Check signals in the viewer's Signals tab, then try again." }],
+                };
+            }
+            // Load full signal data
+            const store = await backpack.signals();
+            const file = await store.load();
+            const selectedSet = new Set(selectedIds);
+            const selected = file.signals.filter((s) => selectedSet.has(s.id));
+            if (selected.length === 0) {
+                return {
+                    content: [{ type: "text", text: `${selectedIds.length} signal ID(s) selected in viewer but none match current signals.json. Try re-detecting signals.` }],
+                };
+            }
+            // Load node labels for evidence context
+            const summaries = await backpack.listOntologies();
+            const nodeLabels = new Map();
+            for (const s of summaries) {
+                try {
+                    const data = await backpack.loadOntology(s.name);
+                    for (const node of data.nodes) {
+                        const label = Object.values(node.properties).find((v) => typeof v === "string" && v.length > 0) ?? node.id;
+                        const propSummary = Object.entries(node.properties)
+                            .filter(([, v]) => v !== undefined && v !== null && String(v).length < 80)
+                            .slice(0, 4)
+                            .map(([k, v]) => `${k}: ${v}`)
+                            .join(", ");
+                        nodeLabels.set(node.id, { label, type: node.type, props: propSummary });
+                    }
+                }
+                catch { /* skip */ }
+            }
+            const blocks = selected.map((s, i) => {
+                const evidence = s.evidenceNodeIds.slice(0, 6).map((nid) => {
+                    const info = nodeLabels.get(nid);
+                    return info ? `  - "${info.label}" (${info.type}${info.props ? `: ${info.props}` : ""})` : `  - ${nid}`;
+                }).join("\n");
+                return `${i + 1}. [${s.severity.toUpperCase()}] ${s.title}\n   Kind: ${s.kind} | Graphs: ${s.graphNames.join(", ")}${s.tags.length > 0 ? ` | Tags: ${s.tags.join(", ")}` : ""}\n   ${s.description}\n   Evidence:\n${evidence || "   (none)"}`;
+            });
+            trackEvent("tool_call", { tool: "backpack_signal_selected" });
+            return {
+                content: [{
+                        type: "text",
+                        text: `${selected.length} signal${selected.length > 1 ? "s" : ""} selected:\n\n${blocks.join("\n\n")}`,
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=signal-tools.js.map

package/dist/mcp/tools/signal-tools.js.map

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

package/dist/sync/auto-sync.d.ts

@@ -0,0 +1,10 @@
+export interface AutoSyncOptions {
+    /** Suppress all output (used in tests). */
+    silent?: boolean;
+}
+/**
+ * Trigger a pull for every registered backpack that has sync state.
+ * Returns immediately; the actual sync runs in the background.
+ */
+export declare function runStartupSync(opts?: AutoSyncOptions): void;
+//# sourceMappingURL=auto-sync.d.ts.map

package/dist/sync/auto-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-sync.d.ts","sourceRoot":"","sources":["../../src/sync/auto-sync.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,eAAoB,GAAG,IAAI,CAM/D"}

package/dist/sync/auto-sync.js

@@ -0,0 +1,81 @@
+// Auto-sync hooks for the local MCP server.
+//
+// Runs in the background on MCP server startup: for each registered backpack
+// that has sync state on disk, run a `pull` so the user picks up any changes
+// that landed via cloud MCP / phone / web while the local MCP wasn't running.
+//
+// All errors are logged to stderr (stdout is reserved for the MCP protocol)
+// and never block server startup.
+import * as crypto from "node:crypto";
+import { listBackpacks } from "../core/backpacks-registry.js";
+import { OAuthClient } from "../auth/oauth.js";
+import { SyncClient } from "./sync-client.js";
+import { SyncRelayClient } from "./sync-relay.js";
+import { readSyncState } from "./sync-state.js";
+/**
+ * Trigger a pull for every registered backpack that has sync state.
+ * Returns immediately; the actual sync runs in the background.
+ */
+export function runStartupSync(opts = {}) {
+    void runStartupSyncAsync(opts).catch((err) => {
+        if (!opts.silent) {
+            process.stderr.write(`auto-sync: top-level error — ${err.message}\n`);
+        }
+    });
+}
+async function runStartupSyncAsync(opts) {
+    let backpacks;
+    try {
+        backpacks = await listBackpacks();
+    }
+    catch (err) {
+        if (!opts.silent) {
+            process.stderr.write(`auto-sync: could not list backpacks — ${err.message}\n`);
+        }
+        return;
+    }
+    for (const entry of backpacks) {
+        const state = await readSyncState(entry.path).catch(() => null);
+        if (!state || !state.relay_url || !state.backpack_id)
+            continue;
+        const tokenProvider = await buildTokenProvider(state.relay_url);
+        if (!tokenProvider) {
+            if (!opts.silent) {
+                process.stderr.write(`auto-sync: ${entry.name} has sync state but no auth available — skipping\n`);
+            }
+            continue;
+        }
+        const relay = new SyncRelayClient({ baseUrl: state.relay_url, token: tokenProvider });
+        const client = new SyncClient({ backpackPath: entry.path, relay });
+        try {
+            const result = await client.pull();
+            if (!opts.silent) {
+                const summary = result.pulled.length === 0 && result.deleted_local.length === 0 && result.errors.length === 0
+                    ? "in sync"
+                    : `pulled ${result.pulled.length}, deleted ${result.deleted_local.length}, errors ${result.errors.length}`;
+                process.stderr.write(`auto-sync: ${entry.name} — ${summary}\n`);
+            }
+        }
+        catch (err) {
+            if (!opts.silent) {
+                process.stderr.write(`auto-sync: ${entry.name} — ${err.message}\n`);
+            }
+        }
+    }
+}
+async function buildTokenProvider(relayUrl) {
+    // Static bearer token from env (CI / scripted setups)
+    if (process.env.BACKPACK_APP_TOKEN) {
+        const tok = process.env.BACKPACK_APP_TOKEN;
+        return () => Promise.resolve(tok);
+    }
+    // OAuth via .mcp.json (same path the MCP server already uses)
+    const clientId = process.env.BACKPACK_APP_CLIENT_ID;
+    const issuerUrl = process.env.BACKPACK_APP_ISSUER_URL;
+    if (!clientId || !issuerUrl)
+        return null;
+    const cacheKey = crypto.createHash("sha256").update(relayUrl).digest("hex").slice(0, 12);
+    const oauth = new OAuthClient(clientId, issuerUrl, cacheKey);
+    return () => oauth.getAccessToken();
+}
+//# sourceMappingURL=auto-sync.js.map

package/dist/sync/auto-sync.js.map

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

package/dist/sync/index.d.ts

@@ -0,0 +1,10 @@
+export { SyncClient, hashContent, parseArtifactId } from "./sync-client.js";
+export type { SyncClientOptions, RegisterOptions } from "./sync-client.js";
+export { SyncRelayClient } from "./sync-relay.js";
+export type { SyncRelayClientOptions, TokenProvider } from "./sync-relay.js";
+export { ARTIFACT_KIND_GRAPH, ARTIFACT_KIND_KB_DOC, SYNC_PROTOCOL_VERSION, SyncVersionConflictError, } from "./types.js";
+export type { ArtifactKind, ArtifactSyncState, BackpackSyncState, ConflictRecord, GraphArtifactContent, KBDocArtifactContent, SyncArtifact, SyncArtifactSummary, SyncBackpack, SyncError, SyncManifest, SyncRunResult, } from "./types.js";
+export { readSyncState, writeSyncState, deleteSyncState, isStateInitialized, emptyArtifactState, } from "./sync-state.js";
+export { runStartupSync } from "./auto-sync.js";
+export type { AutoSyncOptions } from "./auto-sync.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sync/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC5E,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,aAAa,EACb,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/sync/index.js

@@ -0,0 +1,7 @@
+// Public entry point for the sync module.
+export { SyncClient, hashContent, parseArtifactId } from "./sync-client.js";
+export { SyncRelayClient } from "./sync-relay.js";
+export { ARTIFACT_KIND_GRAPH, ARTIFACT_KIND_KB_DOC, SYNC_PROTOCOL_VERSION, SyncVersionConflictError, } from "./types.js";
+export { readSyncState, writeSyncState, deleteSyncState, isStateInitialized, emptyArtifactState, } from "./sync-state.js";
+export { runStartupSync } from "./auto-sync.js";
+//# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAepB,OAAO,EACL,aAAa,EACb,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/sync/sync-client.d.ts

@@ -0,0 +1,80 @@
+import { type BackpackSyncState, type SyncManifest, type SyncRunResult } from "./types.js";
+import { SyncRelayClient } from "./sync-relay.js";
+export interface SyncClientOptions {
+    /** Absolute path to the backpack on disk (where graphs/ + _documents/ live). */
+    backpackPath: string;
+    /** Relay client (constructed by caller, who handles auth). */
+    relay: SyncRelayClient;
+    /** Display name of the backpack (used at register time). */
+    name?: string;
+    /** Color (hex) of the backpack — derived from path by default. */
+    color?: string;
+    /** Tags to assign at register time. */
+    tags?: string[];
+}
+export interface RegisterOptions {
+    name: string;
+    color?: string;
+    tags?: string[];
+    /** Optional pre-existing UUID (for idempotent re-registration). */
+    backpackId?: string;
+}
+export declare class SyncClient {
+    private readonly backpackPath;
+    private readonly relay;
+    private graphsBackend;
+    private docStore;
+    private kbMounts;
+    constructor(opts: SyncClientOptions);
+    /** Read sync state from disk, or null if this backpack is not registered. */
+    getState(): Promise<BackpackSyncState | null>;
+    /**
+     * Register this backpack with the relay. Idempotent — if the backpack is
+     * already registered and the relay knows about it, returns existing state.
+     * If a backpack_id is provided (e.g. from a previous registration), reuses it.
+     */
+    register(opts: RegisterOptions): Promise<BackpackSyncState>;
+    /** Unregister: delete server-side and local sync state. */
+    unregister(): Promise<void>;
+    /**
+     * Compute a status diff without performing any writes. Useful for
+     * `backpack-sync status` and the viewer's pending-changes badge.
+     */
+    status(): Promise<{
+        registered: boolean;
+        state: BackpackSyncState | null;
+        localOnly: string[];
+        remoteOnly: string[];
+        diverged: string[];
+        upToDate: number;
+    }>;
+    /** Push every local artifact whose hash differs from its tracked synced hash. */
+    push(): Promise<SyncRunResult>;
+    /** Pull every remote artifact whose version is newer than the locally tracked one. */
+    pull(): Promise<SyncRunResult>;
+    /** Bidirectional: pull then push. */
+    sync(): Promise<SyncRunResult>;
+    private requireState;
+    private getRelayBaseUrl;
+    private getGraphsBackend;
+    private getKBStore;
+    private scanLocalArtifacts;
+    private writeLocalArtifact;
+    private deleteLocalArtifact;
+    private writeConflictFile;
+    private handleConflict;
+}
+/**
+ * Canonical hash: sorted-keys at every level of the JSON tree, no
+ * whitespace. Matches backpack-app's `repository.canonicalContentHash`
+ * so client-computed hashes survive a round-trip through PostgreSQL JSONB
+ * normalization.
+ */
+export declare function hashContent(content: unknown): string;
+export declare function parseArtifactId(id: string): {
+    kind: string;
+    key: string;
+};
+/** Manifest = SyncManifest, re-exported here for convenience. */
+export type { SyncManifest };
+//# sourceMappingURL=sync-client.d.ts.map

package/dist/sync/sync-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-client.d.ts","sourceRoot":"","sources":["../../src/sync/sync-client.ts"],"names":[],"mappings":"AA2BA,OAAO,EAKL,KAAK,iBAAiB,EAGtB,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAQpB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,KAAK,EAAE,eAAe,CAAC;IACvB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,QAAQ,CAAgC;gBAEpC,IAAI,EAAE,iBAAiB;IAOnC,6EAA6E;IACvE,QAAQ,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAInD;;;;OAIG;IACG,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA2BjE,2DAA2D;IACrD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAajC;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC;QACtB,UAAU,EAAE,OAAO,CAAC;QACpB,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;QAChC,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IAuDF,iFAAiF;IAC3E,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC;IA4CpC,sFAAsF;IAChF,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC;IA2GpC,qCAAqC;IAC/B,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC;YAetB,YAAY;IAU1B,OAAO,CAAC,eAAe;YAYT,gBAAgB;YAQhB,UAAU;YAkBV,kBAAkB;YAsElB,kBAAkB;YA+BlB,mBAAmB;YAmBnB,iBAAiB;YAWjB,cAAc;CA0B7B;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAGpD;AA2BD,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAMzE;AAoBD,iEAAiE;AACjE,YAAY,EAAE,YAAY,EAAE,CAAC"}