@mind-harness/mh-browser 0.0.0-stage → 0.1.0

package/lib/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown

package/lib/typert.host.js

@@ -0,0 +1,356 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+import { z } from 'zod'
+
+import { createTypertRemoteInfo } from '@deepseek-ai/dsh-typert-protocol/remote-info'
+
+let _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema$value
+const _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema = () => (_mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema$value ??= z.string())
+let _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema$value
+const _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema = () => (_mind_harness_mh_browser_mhBrowser_revealHandover_result$schema$value ??= z.object({
+  'status': z.union([z.literal("revealed"), z.literal("not-handing-over"), z.literal("no-tab")]),
+}))
+let _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema$value
+const _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema = () => (_mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema$value ??= z.string())
+
+const $remote = createTypertRemoteInfo({
+  package: '@mind-harness/mh-browser',
+  methods: {
+    'mhBrowser/revealHandover': {
+      service: 'mhBrowser',
+      description: 'The person asked to see the page this Session handed over.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'sessionId',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@mind-harness/mh-browser#mhBrowser/revealHandover:sessionId',
+            create: _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema,
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@mind-harness/mh-browser#mhBrowser/revealHandover:sessionId',
+            create: _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema,
+            jsonSchema: {"type":"string"},
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@mind-harness/mh-browser#mhBrowser/revealHandover:result',
+        create: _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema,
+        jsonSchema: {"type":"object","properties":{"status":{"type":"string","enum":["revealed","not-handing-over","no-tab"]}},"required":["status"],"additionalProperties":true},
+      },
+      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":571,"column":9},
+    },
+  },
+}, z)
+
+export const TYPERT = {
+  package: '@mind-harness/mh-browser',
+  face: 'host',
+  schemas: [
+  ],
+  get invocations() { return $remote.descriptors },
+  model: {
+    "services": [
+      {
+        "description": "Browser service. Launch, windows, tabs, waits, the request channel, and the current representation of each tab. Declared actions and downloads go through the request channel. Person input outside a service dispatch takes the session's browser. `act` returns a snapshot, including on a page that also has an Agent View.",
+        "summary": "Browser service.",
+        "tags": [],
+        "jsDoc": "/**\n * Browser service. Launch, windows, tabs, waits, the request channel, and\n * the current representation of each tab. Declared actions and downloads go\n * through the request channel. Person input outside a service dispatch takes\n * the session's browser. `act` returns a snapshot, including on a page that\n * also has an Agent View.\n */",
+        "key": "mhBrowser",
+        "exportName": "MhBrowserService",
+        "members": [
+          {
+            "kind": "method",
+            "name": "open",
+            "signature": "async open( owner: string, items: { url: string; waitFor?: WaitFor }[], signal?: AbortSignal, ): Promise<(PageView | PageError)[]>"
+          },
+          {
+            "kind": "method",
+            "name": "view",
+            "signature": "async view(owner: string, tab: string, signal?: AbortSignal): Promise<PageView | PageError>"
+          },
+          {
+            "kind": "method",
+            "name": "rememberPresence",
+            "signature": "rememberPresence(owner: string, urls: string[]): void",
+            "summary": "Pages whose current representation is already in the model's presence.",
+            "jsDoc": "/** Pages whose current representation is already in the model's presence. */"
+          },
+          {
+            "kind": "method",
+            "name": "presenceList",
+            "signature": "presenceList(owner: string): HeldPage[]"
+          },
+          {
+            "kind": "method",
+            "name": "presencePut",
+            "signature": "presencePut(owner: string, urls: string[], source: PresenceSource): PresenceReceipt[]"
+          },
+          {
+            "kind": "method",
+            "name": "presenceRemove",
+            "signature": "presenceRemove(owner: string, urls: string[]): PresenceReceipt[]"
+          },
+          {
+            "kind": "method",
+            "name": "presenceLoad",
+            "signature": "presenceLoad( owner: string, folded: { pages: readonly HeldPage[]; removals: readonly PendingOp[] }, ): void",
+            "summary": "The set the session log folds to; taken once per process.",
+            "jsDoc": "/** The set the session log folds to; taken once per process. */"
+          },
+          {
+            "kind": "method",
+            "name": "presenceTakeResume",
+            "signature": "presenceTakeResume(owner: string): boolean"
+          },
+          {
+            "kind": "method",
+            "name": "presenceCheck",
+            "signature": "async presenceCheck( owner: string, which: readonly string[] | 'all', opts?: { baseline?: boolean; replaces?: boolean; force?: boolean; signal?: AbortSignal }, ): Promise<{ text: string; record: PresenceRecord } | undefined>",
+            "summary": "Re-read presence pages and build the next reminder.",
+            "jsDoc": "/**\n * Re-read presence pages and build the next reminder.\n * A tab already on the address is read in place. A check that has to open\n * one closes it before returning. Removals are included, and they cause\n * every remaining page to be read so a page kept out by the byte budget\n * can come back. An empty set has nothing to read and does not wait for the\n * browser; a browser that is down makes every page absent.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "noteWorkspace",
+            "signature": "noteWorkspace(owner: string, target: WriteTarget): void",
+            "summary": "Where a download the page starts may be written: the session's writable root, or why it may not write at all.",
+            "jsDoc": "/**\n * Where a download the page starts may be written: the session's writable\n * root, or why it may not write at all.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "tabs",
+            "signature": "tabs(owner: string): TabInfo[]"
+          },
+          {
+            "kind": "method",
+            "name": "takeClosed",
+            "signature": "takeClosed(owner: string): string[]"
+          },
+          {
+            "kind": "method",
+            "name": "windowId",
+            "signature": "windowId(owner: string, tab: string): Promise<number | undefined>"
+          },
+          {
+            "kind": "method",
+            "name": "fetch",
+            "signature": "async fetch( url: string, opts?: { accept?: string; ifNoneMatch?: string }, ): Promise<FetchResponseBody | { kind: 'error'; reason: string }>"
+          },
+          {
+            "kind": "method",
+            "name": "pushPath",
+            "signature": "async pushPath(owner: string, tab: string, path: string): Promise<void>"
+          },
+          {
+            "kind": "method",
+            "name": "started",
+            "signature": "async started(): Promise<void>"
+          },
+          {
+            "kind": "method",
+            "name": "[testHooks]",
+            "signature": "[testHooks](): TestHooks"
+          },
+          {
+            "kind": "method",
+            "name": "act",
+            "signature": "async act( owner: string, tab: string, action: ActAction, signal?: AbortSignal, ): Promise<PageView>"
+          },
+          {
+            "kind": "method",
+            "name": "holdHandover",
+            "signature": "holdHandover(owner: string, tab: string): void"
+          },
+          {
+            "kind": "method",
+            "name": "releaseHandover",
+            "signature": "releaseHandover(owner: string): void"
+          },
+          {
+            "kind": "method",
+            "name": "capture",
+            "signature": "capture(owner: string, tab: string, signal?: AbortSignal): Promise<Uint8Array | undefined>",
+            "summary": "`undefined` when no screenshot can be taken now: a dialog is open, or the page refused.",
+            "jsDoc": "/** `undefined` when no screenshot can be taken now: a dialog is open, or the page refused. */"
+          },
+          {
+            "kind": "method",
+            "name": "invoke",
+            "signature": "invoke( owner: string, page: string, call: InvokeCall, opts?: { signal?: AbortSignal; readFile?: (value: unknown) => Promise<string> }, ): Promise<InvokeSent>"
+          },
+          {
+            "kind": "method",
+            "name": "download",
+            "signature": "async download( owner: string, url: string, root: string, signal?: AbortSignal, ): Promise<Download>",
+            "summary": "Not queued: it opens no tab, and a long body must not hold up the Session's other calls.",
+            "jsDoc": "/**\n * Not queued: it opens no tab, and a long body must not hold up the\n * Session's other calls. `root` is the directory the session may write.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "controlOf",
+            "signature": "controlOf(owner: string): 'model' | 'person'"
+          },
+          {
+            "kind": "method",
+            "name": "bindPersonTouch",
+            "signature": "bindPersonTouch(fn: (owner: string, urls: string[]) => void): () => void",
+            "summary": "Presence registers this.",
+            "jsDoc": "/** Presence registers this. A hand-back calls it with the touched presence pages. */"
+          },
+          {
+            "kind": "method",
+            "name": "handover",
+            "signature": "handover( owner: string, req: { tab?: string; reason: string }, signal?: AbortSignal, ): Promise<void>",
+            "summary": "Give the browser to the person.",
+            "jsDoc": "/**\n * Give the browser to the person. The named tab stays in use until hand-back.\n * This does not wait; the tool waits on the question card.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "noteSessionTitle",
+            "signature": "noteSessionTitle(owner: string, title: string): void",
+            "summary": "Remember the Session title for its tab group.",
+            "jsDoc": "/** Remember the Session title for its tab group. Empty when the host has none. */"
+          },
+          {
+            "kind": "method",
+            "name": "bringToFront",
+            "signature": "async bringToFront(owner: string): Promise<boolean>",
+            "summary": "Raise the window of this owner's latest tab.",
+            "jsDoc": "/** Raise the window of this owner's latest tab. False when it has no tab. */"
+          },
+          {
+            "kind": "method",
+            "name": "revealHandover",
+            "signature": "@Remote async revealHandover( sessionId: string, signal?: AbortSignal, ): Promise<{ status: 'revealed' | 'not-handing-over' | 'no-tab' }>",
+            "summary": "The person asked to see the page this Session handed over.",
+            "jsDoc": "/** The person asked to see the page this Session handed over. */"
+          },
+          {
+            "kind": "method",
+            "name": "handBack",
+            "signature": "async handBack(owner: string, note?: string): Promise<HandBack>",
+            "summary": "The person answered.",
+            "jsDoc": "/** The person answered. Returns the note, the operation count, and the named tab. */"
+          },
+          {
+            "kind": "method",
+            "name": "releaseIfHeld",
+            "signature": "releaseIfHeld(owner: string): void",
+            "summary": "A stopped handover gives control back.",
+            "jsDoc": "/** A stopped handover gives control back. A finished hand-back is left alone. */"
+          },
+          {
+            "kind": "method",
+            "name": "takePersonHandback",
+            "signature": "takePersonHandback(owner: string): HandBack | undefined",
+            "summary": "The person took over between turns.",
+            "jsDoc": "/**\n * The person took over between turns. The next message they send is the\n * hand-back. A handover that is still waiting on its card is not.\n */"
+          }
+        ],
+        "types": [
+          {
+            "name": "ActAction",
+            "declaration": "export type ActAction = { kind: 'click'; ref: string; double?: boolean; button?: 'left' | 'right' | 'middle'; modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>; } | { kind: 'select'; ref: string; values: string[]; } | { kind: 'press'; key: string; ref?: string; } | { kind: 'fill'; fields: { ref: string; value: string; }[]; } | { kind: 'upload'; ref: string; files: string[]; } | { kind: 'dialog'; accept: boolean; promptText?: string; } | { kind: 'back'; } | { kind: 'wait'; text?: string; textGone?: string; time?: number; } | { kind: 'look'; };"
+          },
+          {
+            "name": "ActionResponse",
+            "declaration": "export interface ActionResponse {\n    name: string;\n    status?: number;\n    location?: string;\n    mediaType?: string;\n    body?: string;\n    bytes?: number;\n    lost?: boolean;\n}"
+          },
+          {
+            "name": "Dialog",
+            "declaration": "export interface Dialog {\n    type: string;\n    message: string;\n}"
+          },
+          {
+            "name": "Download",
+            "declaration": "export type Download = { kind: 'saved'; path: string; url: string; mediaType?: string; bytes: number; sha256: string; observed: string; } | { kind: 'error'; url: string; status?: number; reason: string; };"
+          },
+          {
+            "name": "FetchResponseBody",
+            "declaration": "export interface FetchResponseBody {\n    kind: 'response';\n    finalUrl: string;\n    status: number;\n    mediaType?: string;\n    etag?: string;\n    link?: string;\n    body: Uint8Array;\n}"
+          },
+          {
+            "name": "HandBack",
+            "declaration": "export interface HandBack extends Taken {\n    urls: string[];\n    note?: string;\n    page?: PageView;\n}"
+          },
+          {
+            "name": "HeldPage",
+            "declaration": "export interface HeldPage {\n    url: string;\n    source: PresenceSource;\n    state: 'committed' | 'pending';\n    order: number;\n    seen?: { version?: string; digest: string; observedAt: string; id?: string; } | { absent: string; };\n    title?: string;\n    representation?: 'agent-view' | 'snapshot';\n    body?: string;\n    agentViewError?: string;\n    fragment?: string;\n    requires?: string[];\n    viewUrl?: string;\n}"
+          },
+          {
+            "name": "InvokeCall",
+            "declaration": "export interface InvokeCall {\n    name: string;\n    item?: string;\n    input?: Record<string, unknown>;\n    seen: { digest: string; } | 'not-in-context';\n}"
+          },
+          {
+            "name": "InvokeSent",
+            "declaration": "export interface InvokeSent {\n    schemaRejected: boolean;\n    response?: ActionResponse;\n    page: PageView | PageError;\n}"
+          },
+          {
+            "name": "PageError",
+            "declaration": "export interface PageError {\n    tab?: TabId;\n    url: string;\n    reason: string;\n}"
+          },
+          {
+            "name": "PageView",
+            "declaration": "export interface PageView {\n    tab: TabId;\n    url: string;\n    title: string;\n    observedAt: string;\n    representation: { kind: 'agent-view'; text: string; version?: string; href?: string; } | { kind: 'snapshot'; text: string; agentViewError?: string; agentView?: { version?: string; }; };\n    fragment?: string;\n    status?: number;\n    mediaType?: string;\n    body?: string;\n    inPresence: boolean;\n    dialog?: Dialog;\n    incomplete?: { load: boolean; pendingRequests: number; };\n    waited?: { met: 'text' | 'textGone' | 'time' | false; seconds: number; };\n    download?: Download;\n}"
+          },
+          {
+            "name": "PendingOp",
+            "declaration": "export interface PendingOp {\n    op: 'put' | 'remove';\n    url: string;\n}"
+          },
+          {
+            "name": "PresenceEntryRecord",
+            "declaration": "export interface PresenceEntryRecord {\n    op: PresenceOp;\n    url: string;\n    source: PresenceSource;\n    version?: string;\n    observedAt: string;\n    digest: string;\n    id?: string;\n    reason?: string;\n}"
+          },
+          {
+            "name": "PresenceOp",
+            "declaration": "export type PresenceOp = 'present' | 'added' | 'changed' | 'absent' | 'removed';"
+          },
+          {
+            "name": "PresenceReceipt",
+            "declaration": "export interface PresenceReceipt {\n    url: string;\n    receipt: 'added (pending)' | 'already in presence' | 'removed (pending)' | 'not in presence';\n}"
+          },
+          {
+            "name": "PresenceRecord",
+            "declaration": "export interface PresenceRecord {\n    kind: 'baseline' | 'delta';\n    replaces?: true;\n    entries: PresenceEntryRecord[];\n}"
+          },
+          {
+            "name": "PresenceSource",
+            "declaration": "export type PresenceSource = (typeof PRESENCE_SOURCES)[number];"
+          },
+          {
+            "name": "TabId",
+            "declaration": "export type TabId = string;"
+          },
+          {
+            "name": "TabInfo",
+            "declaration": "export interface TabInfo {\n    tab: TabId;\n    url: string;\n    title: string;\n    occupied: boolean;\n    inPresence: boolean;\n    mayHaveChanged: boolean;\n}"
+          },
+          {
+            "name": "Taken",
+            "declaration": "export interface Taken {\n    operations: number;\n    tabs: string[];\n    from: string;\n    to: string;\n    tab?: string;\n}"
+          },
+          {
+            "name": "TestHooks",
+            "declaration": "export interface TestHooks {\n    crash(): Promise<void>;\n    page(owner: string, tab: string): unknown;\n}"
+          },
+          {
+            "name": "WaitFor",
+            "declaration": "export interface WaitFor {\n    text?: string;\n    textGone?: string;\n    time?: number;\n}"
+          },
+          {
+            "name": "WriteTarget",
+            "declaration": "export type WriteTarget = { root: string; } | { denied: string; code: 'SANDBOX_DENIED' | 'NO_WORKSPACE'; };"
+          }
+        ]
+      }
+    ],
+    "events": [],
+    "objects": []
+  },
+}

package/lib/typert.remote-client.d.ts

@@ -0,0 +1,24 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
+import type {
+  RemoteResult,
+  TypertRemoteInfo,
+  TypertRemoteMethod,
+} from '@deepseek-ai/dsh-typert-protocol'
+
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface TypertRemoteNamespace$6d6842726f77736572 {
+    revealHandover: (sessionId: string, signal?: AbortSignal) => Promise<RemoteResult<{ status: 'revealed' | 'not-handing-over' | 'no-tab'; }>>
+  }
+  interface TypertRemoteMap {
+    'mhBrowser/revealHandover': (sessionId: string, signal?: AbortSignal) => Promise<RemoteResult<{ status: 'revealed' | 'not-handing-over' | 'no-tab'; }>>
+  }
+  interface TypertRemoteNamespaceMap {
+    'mhBrowser': TypertRemoteNamespace$6d6842726f77736572
+  }
+}
+
+export declare const TYPERT_REMOTE: TypertRemoteInfo<{
+  readonly 'mhBrowser/revealHandover': TypertRemoteMethod<{ readonly 'sessionId': string }, { status: 'revealed' | 'not-handing-over' | 'no-tab'; }>
+}>
+export default TYPERT_REMOTE
+//# sourceMappingURL=typert.remote-client.d.ts.map

package/lib/typert.remote-client.js

@@ -0,0 +1,52 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+import { createTypertRemoteInfo } from '@deepseek-ai/dsh-typert-protocol/remote-info'
+
+let _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema$value
+const _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema = () => (_mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema$value ??= z.string())
+let _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema$value
+const _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema = () => (_mind_harness_mh_browser_mhBrowser_revealHandover_result$schema$value ??= z.object({
+  'status': z.union([z.literal("revealed"), z.literal("not-handing-over"), z.literal("no-tab")]),
+}))
+let _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema$value
+const _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema = () => (_mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema$value ??= z.string())
+
+export const TYPERT_REMOTE = createTypertRemoteInfo({
+  package: '@mind-harness/mh-browser',
+  methods: {
+    'mhBrowser/revealHandover': {
+      service: 'mhBrowser',
+      description: 'The person asked to see the page this Session handed over.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'sessionId',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@mind-harness/mh-browser#mhBrowser/revealHandover:sessionId',
+            create: _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema,
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@mind-harness/mh-browser#mhBrowser/revealHandover:sessionId',
+            create: _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema,
+            jsonSchema: {"type":"string"},
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@mind-harness/mh-browser#mhBrowser/revealHandover:result',
+        create: _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema,
+        jsonSchema: {"type":"object","properties":{"status":{"type":"string","enum":["revealed","not-handing-over","no-tab"]}},"required":["status"],"additionalProperties":true},
+      },
+      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":571,"column":9},
+    },
+  },
+}, z)
+
+export default TYPERT_REMOTE

package/lib/types/config.d.ts

@@ -0,0 +1,12 @@
+import z from '@deepseek-ai/schemastery';
+import type { BrowserName } from './types.ts';
+export interface BrowserConfig {
+    presence: {
+        maxBytes: number;
+    };
+    browser: BrowserName;
+    profileDir?: string;
+    headless: boolean;
+}
+export declare const browserConfig: z<BrowserConfig>;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { BrowserConfig } from './config.ts';
+import { MhBrowserService } from './service/service.ts';
+export declare const name = "mh-browser";
+export declare const inject: string[];
+export type Config = BrowserConfig;
+export declare const Config: import("@deepseek-ai/schemastery").default<BrowserConfig>;
+export declare function apply(ctx: Context, config: Config): void;
+export { MhBrowserService };
+export { readAgentView } from './representation/agent-view.ts';
+export type { AgentViewDoc, AgentViewLink, AgentViewRead } from './representation/agent-view.ts';
+export { MhBrowserError, UNKNOWN_TAB, UNKNOWN_TAB_REASON, unknownTab } from './types.ts';
+export type { BrowserName, Dialog, FetchResponse, PageError, PageView, TabId, TabInfo, WaitFor, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/presence/book.d.ts

@@ -0,0 +1,36 @@
+import type { PendingOp } from './fold.ts';
+import type { HeldPage, PresenceReceipt, PresenceSource } from './record.ts';
+interface Removal {
+    url: string;
+    source: PresenceSource;
+}
+/** In-memory presence set for one process. The log is the source of a set that outlives the process. */
+export declare class PresenceBook {
+    private readonly sets;
+    private readonly removals;
+    private readonly loaded;
+    private readonly resume;
+    entries(owner: string): HeldPage[];
+    isShown(owner: string, url: string): boolean;
+    /** Replace the set with addresses the tests already treat as shown. */
+    remember(owner: string, urls: readonly string[]): void;
+    /**
+     * Take the set the log folds to, once per process. Pages put before this
+     * stay. A non-empty folded set is checked on the next step (a resumed
+     * session).
+     */
+    load(owner: string, folded: {
+        pages: readonly HeldPage[];
+        removals: readonly PendingOp[];
+    }): void;
+    takeResume(owner: string): boolean;
+    put(owner: string, urls: readonly string[], source: PresenceSource): PresenceReceipt[];
+    remove(owner: string, urls: readonly string[]): PresenceReceipt[];
+    peekRemovals(owner: string): Removal[];
+    clearRemovals(owner: string): void;
+    apply(owner: string, pages: readonly HeldPage[]): void;
+    /** The Session is gone; the log rebuilds the set if it comes back. */
+    forget(owner: string): void;
+}
+export {};
+//# sourceMappingURL=book.d.ts.map

package/lib/types/presence/fold.d.ts

@@ -0,0 +1,49 @@
+import type { HeldPage, PresenceRecord } from './record.ts';
+export interface PresenceLogEvent {
+    seq: number;
+    type: string;
+    data: unknown;
+}
+interface Carried {
+    id: string;
+    record: PresenceRecord;
+}
+/** A `browser_presence` receipt no reminder has announced yet. */
+export interface PendingOp {
+    op: 'put' | 'remove';
+    url: string;
+}
+/**
+ * Presence as the session log has it. Plain JSON: it is a session projection
+ * state. History reminders fold into `committed`; a reminder still in the
+ * inbox, and one a canceled splice discarded, stays pending on top of it.
+ */
+export interface PresenceLogState {
+    committed: HeldPage[];
+    inbox: {
+        'next-step': Array<Carried | null>;
+        'next-turn': Array<Carried | null>;
+    };
+    /** Discarded since the last reminder entered history; the next step re-announces the set. */
+    discarded: Carried[];
+    /** A reminder entered history since the last summary. */
+    visible: boolean;
+    /** A summary compacted a reminder and none entered history since. */
+    hidden: boolean;
+    /** SHA-256 of each reminder text in history since the last summary. */
+    shown: string[];
+    ops: PendingOp[];
+}
+export declare function initPresenceLog(): PresenceLogState;
+export declare function applyPresenceLog(state: PresenceLogState, event: PresenceLogEvent): PresenceLogState;
+/** The folded set, with pending reminders and unannounced receipts on top. */
+export declare function presenceSet(state: PresenceLogState): {
+    pages: HeldPage[];
+    removals: PendingOp[];
+};
+/** Events at or after `beforeSeq` are a later fork and are ignored. */
+export declare function foldPresence(events: readonly PresenceLogEvent[], beforeSeq?: number): HeldPage[];
+/** The text of a reminder, as `shown` records it. */
+export declare function textDigest(message: unknown): string;
+export {};
+//# sourceMappingURL=fold.d.ts.map

package/lib/types/presence/notice.d.ts

@@ -0,0 +1,8 @@
+/** The sentence a session sees after the person hands the browser back. */
+export declare function takeoverText(taken: {
+    operations: number;
+    tabs: readonly string[];
+    from: string;
+    to: string;
+}): string;
+//# sourceMappingURL=notice.d.ts.map

package/lib/types/presence/plan.d.ts

@@ -0,0 +1,47 @@
+import type { HeldPage, PresenceRecord, PresenceSource } from './record.ts';
+export interface Observation {
+    url: string;
+    ok: boolean;
+    reason?: string;
+    title: string;
+    representation?: 'agent-view' | 'snapshot';
+    version?: string;
+    digest?: string;
+    id?: string;
+    observedAt: string;
+    body?: string;
+    agentViewError?: string;
+    fragment?: string;
+    requires?: string[];
+    /** The Agent View address this page was read from; a `requires` naming it is satisfied. */
+    viewUrl?: string;
+    bytes: number;
+}
+export interface Removal {
+    url: string;
+    source: PresenceSource;
+}
+export interface PlannedReminder {
+    text: string;
+    record: PresenceRecord;
+    next: HeldPage[];
+}
+/**
+ * Decide the next reminder. A baseline lists the whole set; an empty set has
+ * no baseline. A delta lists only what changed. Content that does not fit
+ * stays in the set as an absence and is not truncated. An unchanged check
+ * returns nothing.
+ */
+export declare function planReminder(input: {
+    pages: readonly HeldPage[];
+    observations: readonly Observation[];
+    removals: readonly Removal[];
+    maxBytes: number;
+    baseline: boolean;
+    replaces: boolean;
+    /** Re-announce the current set. A discarded reminder never reached the model. */
+    force?: boolean;
+}): PlannedReminder | undefined;
+/** Walk in put order. A page that does not fit is absent and its bytes are not counted. */
+export declare function applyBudget(pages: readonly HeldPage[], maxBytes: number): HeldPage[];
+//# sourceMappingURL=plan.d.ts.map

package/lib/types/presence/record.d.ts

@@ -0,0 +1,47 @@
+/** Structured presence record carried on a message source. The model sees the rendered text, not this. */
+export declare const PRESENCE_SOURCES: readonly ["person via sidebar", "cwd reference", "model"];
+export type PresenceSource = (typeof PRESENCE_SOURCES)[number];
+export type PresenceOp = 'present' | 'added' | 'changed' | 'absent' | 'removed';
+export interface PresenceEntryRecord {
+    op: PresenceOp;
+    url: string;
+    source: PresenceSource;
+    version?: string;
+    observedAt: string;
+    digest: string;
+    /** The `id` the Agent View declares; `browser_invoke` takes it as well as `url`. */
+    id?: string;
+    reason?: string;
+}
+export interface PresenceRecord {
+    kind: 'baseline' | 'delta';
+    replaces?: true;
+    entries: PresenceEntryRecord[];
+}
+/** One page in the folded presence set. */
+export interface HeldPage {
+    url: string;
+    source: PresenceSource;
+    state: 'committed' | 'pending';
+    order: number;
+    seen?: {
+        version?: string;
+        digest: string;
+        observedAt: string;
+        id?: string;
+    } | {
+        absent: string;
+    };
+    title?: string;
+    representation?: 'agent-view' | 'snapshot';
+    body?: string;
+    agentViewError?: string;
+    fragment?: string;
+    requires?: string[];
+    viewUrl?: string;
+}
+export interface PresenceReceipt {
+    url: string;
+    receipt: 'added (pending)' | 'already in presence' | 'removed (pending)' | 'not in presence';
+}
+//# sourceMappingURL=record.d.ts.map