sealkeep 0.9.0 → 0.11.0

package/dist/src/share.js

@@ -5,7 +5,7 @@ import { canonicalPhrase } from "./mnemonic.js";
 import { isV2 } from "./types.js";
 import { listArchives, readConfig } from "./vault.js";
 import { frameObject, unframeObject } from "./cloud.js";
-import { openArchiveToFile, rewrapArchive } from "../packages/vaultline-crypto/src/index.js";
+import { openArchiveToFile, rewrapArchive } from "../packages/sealkeep-crypto/src/index.js";
 import { materialiseArchive } from "./offload.js";
 import { randomInt } from "node:crypto";
 import { WORDS } from "./mnemonic.js";
@@ -14,7 +14,7 @@ export function generateSharePasscode() {
     return Array.from({ length: PASSCODE_WORDS }, () => WORDS[randomInt(WORDS.length)]).join(" ");
 }
 export async function createShareBundle(dataDir, archiveId, bundlePath, options = { vaultPhrase: "" }) {
-    const record = (await listArchives(dataDir)).find((item) => item.id === archiveId);
+    const record = (await listArchives(dataDir)).find((item) => item.id === archiveId || (archiveId.length >= 4 && /^[0-9a-f]+$/i.test(archiveId) && item.id.toLowerCase().startsWith(archiveId.toLowerCase())));
     if (!record)
         fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
     if (!isV2(record))
@@ -55,7 +55,7 @@ export async function openShareBundle(bundlePath, destination, passcode) {
     const { mkdtemp, rm, writeFile: write } = await import("node:fs/promises");
     const { tmpdir } = await import("node:os");
     const { join } = await import("node:path");
-    const scratch = await mkdtemp(join(tmpdir(), "vaultline-share-"));
+    const scratch = await mkdtemp(join(tmpdir(), "sealkeep-share-"));
     const payload = join(scratch, "payload");
     try {
         await write(payload, ciphertext, { mode: 0o600 });

package/dist/src/shared-spaces.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared spaces — the experience layer over the sharing primitives.
+ *
+ * The goal (set 2026-08-26): working together on one project with one shared
+ * memory should feel like a place, not a pile of flags. Coming to "Shared"
+ * shows what you share and what is shared to you; one copyable command starts
+ * an agent WITH that memory reachable; a joining agent reads a compact
+ * context pack instead of pulling the whole history; members are managed like
+ * a team around a table.
+ *
+ * Everything here composes machinery that already exists and is already
+ * tested: project-scoped recipients (`vault.ts`), the sealed synced content
+ * index (`index-sync.ts`, acceptance 4.3–4.8), bridge mirrors (`bridge.ts`),
+ * and the MCP tools (`mcp.ts`). This module adds no cryptography and no
+ * network calls — it reads local state and writes one markdown file, so the
+ * launcher works offline and never blocks an agent start on a fetch.
+ */
+export type SpaceMember = {
+    id: string;
+    label: string;
+    publicKey: string;
+    addedAt: string;
+    group?: string;
+    project?: string;
+    projectKey?: string;
+};
+export type SharedProject = {
+    name: string;
+    /** Collision-safe local identity; null only for pre-stable-key records and recipients. */
+    projectKey: string | null;
+    /** Unambiguous argument accepted by buildContextPack and the launcher. */
+    ref: string;
+    /** Members scoped to exactly this project (vault-wide members are listed separately — they open everything). */
+    members: SpaceMember[];
+    archives: number;
+    bytes: number;
+    lastSealedAt: string | null;
+};
+export type SharedChannel = {
+    channel: string;
+    mirrorPath: string;
+    bytes: number;
+    updatedAt: string;
+};
+export type SharedSpaces = {
+    /** Projects that have at least one scoped member, or that were asked for by name. */
+    projects: SharedProject[];
+    /** Members with no project scope: they can open everything this vault seals. */
+    vaultWide: SpaceMember[];
+    /** Live-bridge mirrors present on this machine: sessions someone is sharing to us right now (or recently). */
+    channels: SharedChannel[];
+};
+/**
+ * What this machine shares and follows, from local state alone.
+ *
+ * "Shared by me" is the recipient list grouped by project — a member on
+ * `checkout-rewrite` is a grant you made. "Shared to me" appears here as the
+ * bridge mirrors under the vault's own bridge dir (a channel someone gave us)
+ * — cross-account grants land as storage targets + a key, and read the same
+ * way once mounted. No network: the plane is not consulted, so `shared` works
+ * on a plane outage and in tests.
+ */
+export declare function listSharedSpaces(dataDir: string): Promise<SharedSpaces>;
+/** A ref names either a project or a bridge channel; the pack says which it resolved to. */
+export type ContextPack = {
+    ref: string;
+    kind: "project" | "channel";
+    projectKey: string | null;
+    path: string;
+    markdown: string;
+};
+/**
+ * The compact context pack: what a joining agent reads FIRST, instead of the
+ * history. It is deliberately small — member list, the dozen most recent
+ * sealed sessions, the live mirror if one exists, and instructions on how to
+ * reach the rest (search first, recover dry-run). It contains labels, ids,
+ * dates and paths, never a phrase, a key, or transcript content — so the file
+ * itself is safe to sit in a prompt.
+ */
+export declare function buildContextPack(dataDir: string, ref: string): Promise<ContextPack>;
+export type LaunchPlan = {
+    agent: "claude" | "codex";
+    argv: string[];
+    env: Record<string, string>;
+    pack: ContextPack;
+    instruction: string;
+};
+/**
+ * How to start an agent with the shared memory attached. Pure planning — the
+ * CLI decides whether to exec it or print it, and tests assert on the plan.
+ *
+ * The instruction is injected the way each agent accepts context: Claude Code
+ * takes `--append-system-prompt`; Codex takes an initial prompt argument. In
+ * both cases the instruction is one sentence pointing at the pack — the pack
+ * carries the detail, so the injected text stays small and the agent's own
+ * context window is spent on work, not on our preamble.
+ */
+export declare function buildLaunchPlan(dataDir: string, agent: "claude" | "codex", ref: string, passthrough?: string[]): Promise<LaunchPlan>;

package/dist/src/shared-spaces.js

@@ -0,0 +1,214 @@
+/**
+ * Shared spaces — the experience layer over the sharing primitives.
+ *
+ * The goal (set 2026-08-26): working together on one project with one shared
+ * memory should feel like a place, not a pile of flags. Coming to "Shared"
+ * shows what you share and what is shared to you; one copyable command starts
+ * an agent WITH that memory reachable; a joining agent reads a compact
+ * context pack instead of pulling the whole history; members are managed like
+ * a team around a table.
+ *
+ * Everything here composes machinery that already exists and is already
+ * tested: project-scoped recipients (`vault.ts`), the sealed synced content
+ * index (`index-sync.ts`, acceptance 4.3–4.8), bridge mirrors (`bridge.ts`),
+ * and the MCP tools (`mcp.ts`). This module adds no cryptography and no
+ * network calls — it reads local state and writes one markdown file, so the
+ * launcher works offline and never blocks an agent start on a fetch.
+ */
+import { readdir, stat, mkdir, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { createHash } from "node:crypto";
+import { join, basename } from "node:path";
+import { listArchives, readConfig } from "./vault.js";
+import { fail } from "./errors.js";
+import { PRODUCT_SLUG } from "./branding.js";
+/**
+ * What this machine shares and follows, from local state alone.
+ *
+ * "Shared by me" is the recipient list grouped by project — a member on
+ * `checkout-rewrite` is a grant you made. "Shared to me" appears here as the
+ * bridge mirrors under the vault's own bridge dir (a channel someone gave us)
+ * — cross-account grants land as storage targets + a key, and read the same
+ * way once mounted. No network: the plane is not consulted, so `shared` works
+ * on a plane outage and in tests.
+ */
+export async function listSharedSpaces(dataDir) {
+    const config = await readConfig(dataDir);
+    const recipients = (config.recipients ?? []);
+    const vaultWide = recipients.filter((member) => !member.project && !member.projectKey);
+    const byProject = new Map();
+    const scopeOf = (project, projectKey) => projectKey ?? `legacy:${project}`;
+    const summaryFor = (project, projectKey) => {
+        const scope = scopeOf(project, projectKey);
+        const held = byProject.get(scope);
+        if (held)
+            return held;
+        const created = {
+            name: project,
+            projectKey: projectKey ?? null,
+            members: [],
+            archives: 0,
+            bytes: 0,
+            last: null,
+        };
+        byProject.set(scope, created);
+        return created;
+    };
+    for (const member of recipients) {
+        if (!member.project && !member.projectKey)
+            continue;
+        summaryFor(member.project ?? member.projectKey, member.projectKey).members.push(member);
+    }
+    const records = await listArchives(dataDir);
+    for (const record of records) {
+        const project = record.version === 2 ? record.source.project : undefined;
+        if (!project)
+            continue;
+        const projectKey = record.version === 2 ? record.source.projectKey : undefined;
+        const entry = summaryFor(project, projectKey);
+        entry.archives += 1;
+        entry.bytes += record.source.bytes;
+        if (!entry.last || record.createdAt > entry.last)
+            entry.last = record.createdAt;
+    }
+    // A project is "shared" when someone was let in; a project with archives but
+    // no members still lists (with zero members) so the add-member UI has
+    // something to attach to.
+    const projects = [...byProject.values()]
+        .sort((left, right) => left.name.localeCompare(right.name)
+        || (left.projectKey ?? "").localeCompare(right.projectKey ?? ""))
+        .map((project) => ({
+        name: project.name,
+        projectKey: project.projectKey,
+        ref: project.projectKey ?? project.name,
+        members: project.members,
+        archives: project.archives,
+        bytes: project.bytes,
+        lastSealedAt: project.last,
+    }));
+    const channels = [];
+    const bridgeDir = join(dataDir, "bridge");
+    const entries = await readdir(bridgeDir).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.endsWith(".mirror.jsonl"))
+            continue;
+        const mirrorPath = join(bridgeDir, entry);
+        const info = await stat(mirrorPath).catch(() => null);
+        if (!info)
+            continue;
+        channels.push({ channel: entry.replace(/\.mirror\.jsonl$/, ""), mirrorPath, bytes: info.size, updatedAt: info.mtime.toISOString() });
+    }
+    channels.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+    return { projects, vaultWide, channels };
+}
+const slug = (ref) => ref.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "shared";
+/**
+ * The compact context pack: what a joining agent reads FIRST, instead of the
+ * history. It is deliberately small — member list, the dozen most recent
+ * sealed sessions, the live mirror if one exists, and instructions on how to
+ * reach the rest (search first, recover dry-run). It contains labels, ids,
+ * dates and paths, never a phrase, a key, or transcript content — so the file
+ * itself is safe to sit in a prompt.
+ */
+export async function buildContextPack(dataDir, ref) {
+    if (!ref.trim())
+        fail("invalid_argument", "A project name or bridge channel is required");
+    const spaces = await listSharedSpaces(dataDir);
+    const channel = spaces.channels.find((c) => c.channel === ref);
+    const exactProject = spaces.projects.find((project) => project.projectKey === ref);
+    const namedProjects = spaces.projects.filter((project) => project.name === ref);
+    if (!exactProject && namedProjects.length > 1) {
+        fail("invalid_argument", `More than one stable project is named ${ref}; use one exact project ref so memories from different folders are not combined: ${namedProjects.map((project) => project.ref).join(", ")}`);
+    }
+    const project = exactProject ?? namedProjects[0];
+    const kind = channel && !project ? "channel" : "project";
+    const displayRef = project?.name ?? ref;
+    // A channel pack deliberately lists NO sessions: a channel is not a project,
+    // and enumerating the vault's newest archives into a pack that rides shared
+    // prompts would leak every project's existence to whoever is on the channel.
+    const records = kind === "channel" || !project ? [] : (await listArchives(dataDir))
+        .filter((record) => record.version === 2 && (project.projectKey
+        ? record.source.projectKey === project.projectKey
+        : !record.source.projectKey && record.source.project === project.name))
+        .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))
+        .slice(0, 12);
+    const members = [
+        ...(project?.members ?? []).map((m) => `- ${m.label} — member of “${displayRef}”`),
+        ...spaces.vaultWide.map((m) => `- ${m.label} — member of everything in this vault`),
+    ];
+    const lines = [];
+    lines.push(`# Sealkeep shared memory — ${displayRef}`);
+    lines.push("");
+    lines.push(`Generated ${new Date().toISOString()} on ${hostname()}. This file is for the agent starting a session here.`);
+    lines.push("");
+    lines.push(`This ${kind === "channel" ? "session is following a live shared channel" : "project has a sealed, shared history"} in Sealkeep. You (the agent) can reach it through the ${PRODUCT_SLUG}_* MCP tools.`);
+    lines.push("");
+    lines.push("## What to do");
+    lines.push(kind === "project"
+        ? `1. Search the shared history BEFORE you read the code or make any change — treat this as a required first step, not an option: call \`${PRODUCT_SLUG}_search\` with your question (project: “${displayRef}”${project?.projectKey ? `, projectKey: “${project.projectKey}”` : ""}). The working files show WHAT exists, not the decisions, constraints, and gotchas the team already settled — those live only in the sealed sessions, and skipping this repeats solved work or breaks an invariant you cannot see.`
+        : `1. The live mirror below is your primary context. Search the sealed history only for the project the driver names — ask over the channel rather than searching vault-wide.`);
+    lines.push(`2. Restore only what you need: \`${PRODUCT_SLUG}_recover\` is dry-run by default; name the session id the search gave you.`);
+    if (kind === "project")
+        lines.push(`3. Before taking new work, call \`${PRODUCT_SLUG}_team\` — if a teammate already STARTED the same thing, coordinate instead of doubling it.`);
+    if (channel) {
+        lines.push(`4. A live mirror of the shared session is at \`${channel.mirrorPath}\` — read it for current state. It grows every few seconds while the driver works; re-read it rather than caching.`);
+        lines.push(`5. To speak to the driver and the other followers, call \`${PRODUCT_SLUG}_bridge_push\` with this channel ("${ref}") — your words reach the driver's agent on its next turn. Check \`${PRODUCT_SLUG}_bridge_inbox\` between tasks for what teammates said to you.`);
+    }
+    lines.push("");
+    if (members.length) {
+        lines.push("## Who is in this space");
+        lines.push(...members);
+        lines.push("");
+    }
+    if (records.length) {
+        lines.push("## Recent sealed sessions");
+        for (const record of records) {
+            lines.push(`- ${record.id.slice(0, 12)} · ${record.source.agent} · ${basename(record.source.path)} · ${record.createdAt.slice(0, 10)}`);
+        }
+        lines.push("");
+    }
+    lines.push("## Ground rules");
+    lines.push("- Cite the session id when you reuse a decision from the shared history, so provenance survives.");
+    lines.push("- Never paste secrets into a session that seals into a shared project — members can read what the team sealed.");
+    lines.push(`- If the ${PRODUCT_SLUG}_* tools are missing from your tool list, tell the user to run \`${PRODUCT_SLUG} mcp install\`.`);
+    lines.push("");
+    const markdown = lines.join("\n");
+    const dir = join(dataDir, "context");
+    await mkdir(dir, { recursive: true });
+    // Injective filename: the slug reads well, the hash keeps “web.app”,
+    // “web app” and a channel named like a project from silently sharing a file.
+    const canonicalRef = project?.projectKey ?? ref;
+    const distinct = createHash("sha256").update(`${kind}:${canonicalRef}`).digest("hex").slice(0, 8);
+    const path = join(dir, `${slug(displayRef)}-${distinct}.md`);
+    await writeFile(path, markdown, { mode: 0o600 });
+    return { ref, kind, projectKey: project?.projectKey ?? null, path, markdown };
+}
+/**
+ * How to start an agent with the shared memory attached. Pure planning — the
+ * CLI decides whether to exec it or print it, and tests assert on the plan.
+ *
+ * The instruction is injected the way each agent accepts context: Claude Code
+ * takes `--append-system-prompt`; Codex takes an initial prompt argument. In
+ * both cases the instruction is one sentence pointing at the pack — the pack
+ * carries the detail, so the injected text stays small and the agent's own
+ * context window is spent on work, not on our preamble.
+ */
+export async function buildLaunchPlan(dataDir, agent, ref, passthrough = []) {
+    const pack = await buildContextPack(dataDir, ref);
+    const instruction = `Sealkeep: shared team memory for “${ref}” is attached to this session. ` +
+        `Before you read the code or make any change, read ${pack.path} and search the shared history with the ${PRODUCT_SLUG}_* MCP tools — the working files do not show the team's prior decisions, constraints, or gotchas, so searching first is a required step, not an option. Recover dry-run.`;
+    const argv = agent === "claude"
+        ? ["claude", "--append-system-prompt", instruction, ...passthrough]
+        : ["codex", ...passthrough, instruction];
+    return {
+        agent,
+        argv,
+        env: {
+            SEALKEEP_CONTEXT: pack.path,
+            SEALKEEP_SHARED_REF: pack.projectKey ?? ref,
+            ...(pack.projectKey ? { SEALKEEP_PROJECT_KEY: pack.projectKey } : {}),
+        },
+        pack,
+        instruction,
+    };
+}

package/dist/src/source-reader.d.ts

@@ -0,0 +1,73 @@
+import { type Envelope } from "../packages/sealkeep-crypto/src/index.js";
+import { type ArchiveRecord, type ArchiveRecordV2 } from "./types.js";
+import type { ArchiveCatalogFacts, ContentIndex } from "./search.js";
+/** An immutable citation. Storage aliases may change; these source facts may not. */
+export type SourceReference = {
+    version: 1;
+    archiveId: string;
+    envelopeArchiveId: string;
+    sourceSha256: string;
+    sourceBytes: number;
+    ciphertextSha256: string;
+    project?: string;
+    projectKey?: string;
+    spaceKey?: string;
+};
+export type TeamSourceAccess = {
+    spaceKey: string;
+    membershipVersion: number;
+    index: ContentIndex;
+    readGuard?: import("./cloud.js").TeamReadGuard;
+};
+export type SourceReadLimits = {
+    maxWireBytes?: number;
+    maxDecodedBytes?: number;
+    signal?: AbortSignal;
+};
+export type SourceRange = {
+    start: number;
+    end: number;
+};
+export type SourceRead = {
+    source: SourceReference;
+    record: ArchiveRecord;
+    bytes: Buffer;
+    byteStart: number;
+    byteEnd: number;
+    wireBytes: number;
+    decodedBytes: number;
+    assertCurrent: () => Promise<void>;
+};
+export declare const envelopeDigest: (envelope: Envelope) => string;
+export declare function sourceReference(id: string, facts: ArchiveCatalogFacts, scope?: {
+    project?: string;
+    projectKey?: string;
+    spaceKey?: string;
+}): SourceReference;
+export declare function resolveSourceReference(dataDir: string, phrase: string, archiveId: string, project: string, projectKey?: string): Promise<SourceReference>;
+declare function catalogEntry(index: ContentIndex, id: string, spaceKey?: string): {
+    line: string[];
+    facts: ArchiveCatalogFacts;
+    plaintextBytes: number;
+};
+export declare function teamCatalogEntry(access: TeamSourceAccess, id: string): ReturnType<typeof catalogEntry>;
+/** Shared by search snippets, context reads and explicit Team restoration. */
+export declare function resolveTeamArchive(dataDir: string, id: string, access: TeamSourceAccess, limits?: SourceReadLimits): Promise<{
+    record: ArchiveRecordV2;
+    teamRead: {
+        framed: Buffer<ArrayBufferLike>;
+        grants: Set<string>;
+        assertCurrent: (refs?: Iterable<string>) => Promise<void>;
+        spaceKey: string;
+        membershipVersion: number;
+        index: ContentIndex;
+        readGuard?: import("./cloud.js").TeamReadGuard;
+    };
+    guard: import("./cloud.js").TeamReadGuard;
+}>;
+/** Resolves the exact immutable source again for every read; citations are never permissions. */
+export declare function readSourceBytes(dataDir: string, phrase: string, source: SourceReference, options?: SourceReadLimits & {
+    range?: SourceRange;
+    chunkIndex?: number;
+}): Promise<SourceRead>;
+export {};