sealkeep 0.8.1 → 0.11.0

package/dist/src/branding.d.ts

@@ -12,7 +12,7 @@
  * literals where they live:
  *   - the npm package name ("vaultline") — republish + deprecate
  *   - the data directory (~/.vaultline) and archive/file extensions
- *     (.vlarchive, .vlmeta, .vlshare, .vlindex)
+ *     (.skarchive, .skmeta, .vlshare, .skindex)
  *   - keystore service ids ("vaultline-cloud", provider credential refs)
  *   - managed cloud object paths (vaultline/<account>/…) and the plane URL
  *   - wire markers (VLA1 frame magic, AAD strings, HKDF info strings) —
@@ -29,3 +29,26 @@ export declare const PRODUCT_ORG = "SPALA AI";
 export declare const PRODUCT_URL = "https://sealkeep.spala.ai";
 /** The visible folder a personal Drive keeps sealed archives in. */
 export declare const DRIVE_FOLDER_DEFAULT = "Sealkeep";
+/**
+ * The folder NEW archives land in inside a bring-your-own bucket.
+ *
+ * This was written out by hand in nine places, so renaming the product moved
+ * some of them and left the rest — the web wizard would write `sealkeep/` while
+ * the CLI still wrote `vaultline/` into the same bucket. It is one constant now.
+ * The read path in offload.ts deliberately does NOT use it: that one derives the
+ * prefix from the object key it is fetching, which is the only correct answer
+ * for an archive already written.
+ */
+export declare const STORAGE_PREFIX_DEFAULT = "sealkeep";
+/**
+ * What each storage provider is CALLED, as distinct from what it is keyed by.
+ *
+ * The ids are frozen — they sit inside every archive record and cross the wire
+ * to the control plane, so "vaultline" stays "vaultline" for as long as those
+ * archives exist. That is a fact about storage, not a thing to show a person.
+ * The panel already understood this and rendered a label; the CLI printed the
+ * raw id, which is the only place the old brand still surfaced to a reader.
+ */
+export declare const PROVIDER_LABEL: Record<string, string>;
+/** The provider's display name, falling back to its id for anything unlisted. */
+export declare const providerLabel: (id: string) => string;

package/dist/src/branding.js

@@ -12,7 +12,7 @@
  * literals where they live:
  *   - the npm package name ("vaultline") — republish + deprecate
  *   - the data directory (~/.vaultline) and archive/file extensions
- *     (.vlarchive, .vlmeta, .vlshare, .vlindex)
+ *     (.skarchive, .skmeta, .vlshare, .skindex)
  *   - keystore service ids ("vaultline-cloud", provider credential refs)
  *   - managed cloud object paths (vaultline/<account>/…) and the plane URL
  *   - wire markers (VLA1 frame magic, AAD strings, HKDF info strings) —
@@ -29,3 +29,33 @@ export const PRODUCT_ORG = "SPALA AI";
 export const PRODUCT_URL = "https://sealkeep.spala.ai";
 /** The visible folder a personal Drive keeps sealed archives in. */
 export const DRIVE_FOLDER_DEFAULT = PRODUCT_NAME;
+/**
+ * The folder NEW archives land in inside a bring-your-own bucket.
+ *
+ * This was written out by hand in nine places, so renaming the product moved
+ * some of them and left the rest — the web wizard would write `sealkeep/` while
+ * the CLI still wrote `vaultline/` into the same bucket. It is one constant now.
+ * The read path in offload.ts deliberately does NOT use it: that one derives the
+ * prefix from the object key it is fetching, which is the only correct answer
+ * for an archive already written.
+ */
+export const STORAGE_PREFIX_DEFAULT = PRODUCT_SLUG;
+/**
+ * What each storage provider is CALLED, as distinct from what it is keyed by.
+ *
+ * The ids are frozen — they sit inside every archive record and cross the wire
+ * to the control plane, so "vaultline" stays "vaultline" for as long as those
+ * archives exist. That is a fact about storage, not a thing to show a person.
+ * The panel already understood this and rendered a label; the CLI printed the
+ * raw id, which is the only place the old brand still surfaced to a reader.
+ */
+export const PROVIDER_LABEL = {
+    vaultline: `${PRODUCT_NAME} managed`,
+    s3: "Amazon S3",
+    r2: "Cloudflare R2",
+    b2: "Backblaze B2",
+    gcs: "Google Cloud",
+    gdrive: "Google Drive"
+};
+/** The provider's display name, falling back to its id for anything unlisted. */
+export const providerLabel = (id) => PROVIDER_LABEL[id] ?? id;

package/dist/src/bridge.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Realtime Bridge — Watch-P0.
+ *
+ * Live, read-only sharing of one ongoing agent session, built on the archive
+ * pipeline instead of beside it. A driver's machine tails the session file and,
+ * every few seconds, seals the bytes that have appeared since the last delta
+ * into a tiny object and pushes it to managed storage under a per-channel
+ * prefix. Members poll that prefix, pull each delta, unseal it, and append it
+ * to a local **mirror** file their own agent can read — so two or three people
+ * can follow one session live.
+ *
+ * What this module deliberately is NOT (documented rungs, not yet built):
+ *  - no write/inject path — a member cannot drive the agent (see
+ *    docs/realtime-bridge.md; injection needs a spike and signed identity);
+ *  - no cross-account key exchange — P0 shares within one account's own
+ *    devices/members, which reuse the vault phrase to unseal, exactly as the
+ *    open path already does. Cross-account is rung 4.
+ *
+ * The one promise the archive pipeline makes is kept here unchanged: every
+ * delta is sealed on the driver's machine before a byte leaves it, and the
+ * plane relays ciphertext only. A bridge is the seal loop running continuously.
+ *
+ * Integrity: each delta carries the sha256 of the whole session prefix up to
+ * its start. A member applies a delta only if that hash matches the mirror it
+ * has so far — so a missed, duplicated, or out-of-order delta is caught, and a
+ * transcript that was rewritten (compaction, resume) trips the check and asks
+ * for a fresh full snapshot rather than silently corrupting the mirror.
+ */
+import type { BackendName } from "./secrets.js";
+/** The vault_ref a delta is stored under. Ordered by zero-padded seq so a plain string sort is a seq sort. */
+export declare function deltaRef(channel: string, seq: number): string;
+/** Pull the seq back out of a delta ref, or null if it is not one of this channel's. */
+export declare function seqOf(channel: string, vaultRef: string): number | null;
+/**
+ * The metadata a delta announces about itself, sealed inside the object next to
+ * the ciphertext so the plane never sees it. `prefixSha` is the hash of the
+ * session up to `start`; `prefixBytes` is `start`. A member checks both before
+ * appending.
+ */
+export type DeltaMeta = {
+    channel: string;
+    seq: number;
+    start: number;
+    end: number;
+    prefixSha: string;
+    prefixBytes: number;
+    at: string;
+};
+/**
+ * Seal one byte-range as a bridge delta and push it. The range's bytes are the
+ * plaintext; the DeltaMeta rides in the envelope's adapter slot so it is sealed
+ * too. Returns the ref it was stored under.
+ */
+export declare function publishDelta(dataDir: string, input: {
+    channel: string;
+    seq: number;
+    bytes: Buffer;
+    start: number;
+    prefixSha: string;
+}, phrase: string, preferred?: BackendName): Promise<{
+    ref: string;
+    storedBytes: number;
+}>;
+/** A delta as a member sees it after pulling and unsealing: its meta and its plaintext bytes. */
+export type OpenedDelta = {
+    meta: DeltaMeta;
+    bytes: Buffer;
+};
+/** Pull one delta by ref, unseal it, and recover its meta. */
+export declare function openDelta(dataDir: string, ref: string, phrase: string, preferred?: BackendName): Promise<OpenedDelta>;
+/**
+ * Advance a member's mirror file by applying a delta, refusing anything the
+ * hash chain does not vouch for. Returns what happened so a caller (CLI, MCP,
+ * dashboard) can react: `applied` grew the mirror; `stale` is an already-seen
+ * delta (idempotent, safe to skip); `gap` means an earlier delta is missing;
+ * `reset` means the session was rewritten upstream and the mirror must be
+ * rebuilt from a fresh snapshot.
+ */
+export declare function applyDeltaToMirror(mirrorPath: string, delta: OpenedDelta): Promise<"applied" | "stale" | "gap" | "reset">;
+/**
+ * One publisher pass: read the session file, and if it has grown since `fromByte`,
+ * seal the new bytes as the next delta. Returns the new high-water mark and the
+ * ref, or null when nothing changed. Caller owns the loop and the seq counter.
+ */
+export declare function publishOnce(dataDir: string, input: {
+    channel: string;
+    seq: number;
+    sessionPath: string;
+    fromByte: number;
+}, phrase: string, preferred?: BackendName): Promise<{
+    ref: string;
+    seq: number;
+    newHighWater: number;
+    prefixSha: string;
+} | null>;
+/**
+ * One member pass: list the channel's delta refs the account holds, and apply
+ * every one at or after `fromSeq` in order. Returns the seqs applied and the
+ * next seq to ask for. Missing/rewritten deltas surface as `gaps`/`needsReset`
+ * rather than a corrupted mirror.
+ */
+export declare function watchOnce(dataDir: string, input: {
+    channel: string;
+    fromSeq: number;
+    mirrorPath: string;
+}, phrase: string, preferred?: BackendName): Promise<{
+    applied: number[];
+    nextSeq: number;
+    gaps: boolean;
+    needsReset: boolean;
+}>;
+export type BridgeMessageKind = "suggest" | "note" | "handoff";
+export type BridgeMessage = {
+    channel: string;
+    /** Stable per-vault-per-machine sender id (8 hex chars), never reused across senders. */
+    sender: string;
+    /** Human label for the sender, e.g. a hostname or a name the sender chose. */
+    from: string;
+    seq: number;
+    kind: BridgeMessageKind;
+    text: string;
+    at: string;
+    /** Set when the driver approved this with edited text — the injection says so. */
+    reworded?: boolean;
+};
+export declare function messageRef(channel: string, sender: string, seq: number): string;
+/** Parse a message ref back into its sender and seq, or null if it is not this channel's. */
+export declare function messageRefOf(channel: string, vaultRef: string): {
+    sender: string;
+    seq: number;
+} | null;
+type SenderState = {
+    id: string;
+    label: string;
+    outSeq: Record<string, number>;
+};
+/**
+ * This machine's bridge identity: minted once, kept next to the mirrors. The
+ * label defaults to the hostname and is what teammates see; the id is what
+ * keeps two machines' refs from colliding.
+ */
+export declare function bridgeSender(dataDir: string): Promise<SenderState>;
+/** Seal one message for a channel. Pure of transport, so tests need no cloud. */
+export declare function sealBridgeMessage(message: BridgeMessage, phrase: string): {
+    ref: string;
+    blob: Buffer;
+};
+/** Open a pulled message blob back into the message, meta and text both verified by the seal. */
+export declare function openBridgeMessageBlob(blob: Buffer, phrase: string): BridgeMessage;
+/** A tiny mutex around sender.json, so two pushes in two terminals cannot mint one seq. */
+export declare function withSenderLock<T>(dataDir: string, work: () => Promise<T>): Promise<T>;
+/** The hard ceiling a single message may carry into a prompt. Enforced at push, re-enforced at injection. */
+export declare const MESSAGE_TEXT_MAX = 4000;
+/**
+ * Push one message into a channel. The seq is RESERVED under a lock before the
+ * upload starts, so concurrent pushes from one machine mint distinct refs; a
+ * failed upload rolls the reservation back when nothing newer claimed it.
+ */
+export declare function publishBridgeMessage(dataDir: string, input: {
+    channel: string;
+    kind: BridgeMessageKind;
+    text: string;
+    from?: string;
+}, phrase: string, preferred?: BackendName): Promise<{
+    ref: string;
+    message: BridgeMessage;
+}>;
+/** Where a channel's inbox (every teammate message, decrypted, as JSONL) lives. */
+export declare function defaultInboxPath(dataDir: string, channel: string): string;
+/** Where the not-yet-delivered queue lives — what the prompt hook drains. */
+export declare function pendingPath(dataDir: string, channel: string): string;
+/**
+ * One pull pass: list the channel's message refs, open the unseen ones, append
+ * them to the inbox log AND the pending queue, and remember what was seen — so
+ * a message is delivered exactly once no matter how many loops poll.
+ */
+export declare function pullBridgeMessages(dataDir: string, channel: string, phrase: string, preferred?: BackendName): Promise<{
+    fresh: BridgeMessage[];
+    mode: CooperationMode;
+}>;
+export declare function heldPath(dataDir: string, channel: string): string;
+/**
+ * Cooperation mode — the channel owner's choice of how far teammates' words
+ * spread: `observe` = humans see them in the loop, the agent never does;
+ * `suggest` = held for the driver's yes/no/reword; `open` = delivered straight
+ * into the agent's next turn. `approval: true` is the older spelling of
+ * `suggest` and still honoured.
+ */
+export type CooperationMode = "observe" | "suggest" | "open";
+type ChannelSettings = {
+    approval?: boolean;
+    mode?: CooperationMode;
+};
+export declare function cooperationModeOf(settings: ChannelSettings): CooperationMode;
+export declare function channelSettings(dataDir: string, channel: string): Promise<ChannelSettings>;
+export declare function setChannelMode(dataDir: string, channel: string, mode: CooperationMode): Promise<void>;
+export declare function listHeld(dataDir: string, channel: string): Promise<BridgeMessage[]>;
+/**
+ * The driver's verdict on held messages. `index` is 1-based into the held list
+ * (or "all"); approving moves messages to pending — with `reword`, the text is
+ * replaced and the message is marked reworded, so the injection says so and a
+ * teammate is never quoted on words the driver wrote. Rejecting drops from the
+ * queue; the inbox log keeps what was actually said either way.
+ */
+export declare function resolveHeld(dataDir: string, channel: string, verdict: {
+    approve: boolean;
+    index: number | "all";
+    reword?: string;
+}): Promise<{
+    resolved: BridgeMessage[];
+    remaining: number;
+}>;
+/**
+ * Drain the pending queue: return its messages and truncate it. The caller is
+ * whatever hands teammates' words to the agent — the UserPromptSubmit hook on
+ * the driver's machine, or the `sealkeep_bridge_inbox` MCP tool when the agent
+ * pulls for itself (Codex has no prompt hook; polling a tool is its pull).
+ */
+export declare function drainPending(dataDir: string, channel: string, limit?: number): Promise<BridgeMessage[]>;
+/** How many messages still wait in pending — the overflow note the hook appends. */
+export declare function pendingCount(dataDir: string, channel: string): Promise<number>;
+export declare function promptInjection(messages: BridgeMessage[], stillWaiting?: number): string;
+/** Everything this machine knows about its channels — the bare `sealkeep bridge` status view. */
+export declare function listChannelStatus(dataDir: string): Promise<Array<{
+    channel: string;
+    mode: CooperationMode;
+    mirrorBytes: number;
+    pending: number;
+    held: number;
+}>>;
+/** Where a member's mirror of a channel lives by default. */
+export declare function defaultMirrorPath(dataDir: string, channel: string): string;
+export {};