@vibesdotdev/session 0.0.0-stage → 1.0.0-rc.2

package/dist/docs/session.docs.descriptor.js

@@ -0,0 +1,589 @@
+/**
+ * Session docs/topic descriptors (Rule 11).
+ *
+ * `@vibesdotdev/session` ships five `tools/tool` descriptors
+ * (session, session-todo, session-scratchpad, session-collaborate,
+ * session-workspace), eleven storage record/manifest descriptors, and three
+ * CLI groups (session, session.todo, session.scratchpad) — but had zero
+ * docs/topic coverage. This file defines the parent `session` topic plus
+ * child topics so the docs surface (CLI `vibes docs`, web, in-app, MCP
+ * tool-help) can resolve real help instead of a synthesized stub.
+ *
+ * Topic tree:
+ *   session              (parent — overview + manifest + tools + CLI map)
+ *   ├─ session.state     (session-state storage manifest + records)
+ *   ├─ session.todo      (session-todo tool + todo CLI group)
+ *   ├─ session.scratchpad(session-scratchpad tool + scratchpad CLI group)
+ *   └─ session.collaborate (session-collaborate + session-workspace tools)
+ *
+ * Each child is registered in `session.plugin.ts` `descriptors[]`.
+ */
+// -- parent: session ---------------------------------------------------------
+const sessionOverviewMarkdown = `---
+title: Session
+summary: Participant sessions — lifecycle, persistent context, todos, scratchpad, collaboration, and paired workspaces
+tags: [session, lifecycle, context, dev-workflow]
+order: 1
+surfaces: [cli, web, in-app, mcp]
+hardware: [consumer, cloud]
+---
+
+# Session
+
+A **session** is the unit of persistent context for a participant working in a
+repository. It tracks which workspace you are in, what you are doing (todos),
+free-form notes (scratchpad), cross-participant handoff messages
+(collaborate), and any externally paired directories (workspace).
+
+\`@vibesdotdev/session\` exposes this capability through five runtime tools, an
+eleven-descriptor storage layer, and three CLI groups.
+
+The kernel owns one session client (runtime/client id session) per retained root.
+The session/manager context and getVibesSessionManagerAsync resolve its manager.
+The client also owns live MCP connection handles; durable bindings remain in
+session.state. Plugin activation enables synchronous transport access. An
+inactive owner refuses session-client-unavailable; a fabricated runtime refuses
+session-runtime-unidentified. Manager initialization can retry after failure,
+and runtime disposal closes the manager and transport handles.
+
+## Host composition
+
+- \`@vibesdotdev/session/core.plugin\` (also \`/browser.plugin\`) registers the
+  scope-neutral client, context, shared tools, records, events, subscription,
+  backup target and docs; it imports no consumer or CLI loader.
+- \`@vibesdotdev/session/cloud.plugin\` adds the cloud init variant. Init refuses
+  \`UNAVAILABLE\` / \`session-init-consumer-required\`.
+- \`@vibesdotdev/session/consumer.plugin\` and compatible \`/plugin\` retain
+  consumer init, the knowledge source, CLI commands and binding restoration.
+- \`@vibesdotdev/session/cli/plugin\` adds only CLI registrations when composing
+  slices explicitly after the capability plugin.
+- \`@vibesdotdev/session/tui/plugin\` adds the consumer sessions list/detail,
+  open command and registry. Compose the TUI owner before rendering.
+- \`@vibesdotdev/session/svelte/plugin\` registers Svelte tool-call widgets.
+
+Choose one capability composition per host (plugin id \`session\`).
+The host supplies storage adapters. TUI detail tabs load lazily; archived
+sessions offer no resume control, text-entry focus suppresses action shortcuts,
+Pause targets the selected id, and Workflow Monitor receives its session context.
+
+## Tools
+
+All tools are \`tools/tool\` descriptors using the discriminated \`action\`
+pattern (one tool, many actions). Each requires the \`session/manager\` context
+except \`session-workspace\`, which resolves the active session itself.
+
+| Tool id | Default action | Actions | Topic |
+|---------|----------------|---------|-------|
+| \`session\` | \`status\` | init, get, status, context, packet, list, search, update, pause, resume, archive, snapshot | this page |
+| \`session-todo\` | \`list\` | add, batch-add, list, get, update, complete, tree | \`session.todo\` |
+| \`session-scratchpad\` | \`list\` | write, read, list, search | \`session.scratchpad\` |
+| \`session-collaborate\` | \`list\` | send, list, mark-read | \`session.collaborate\` |
+| \`session-workspace\` | — | pair, unpair, list | \`session.collaborate\` |
+
+## Session lifecycle
+
+The \`session\` tool drives the lifecycle. Invoke it with an \`action\`:
+
+:::usage{language="ts"}
+import type { VibesRuntime } from '@vibesdotdev/kernel';
+
+// The handed runtime: context.runtime in a command, event.locals.runtime in
+// SvelteKit, the onActivate runtime in a plugin.
+declare const runtime: VibesRuntime;
+
+// Start (or attach to) a session for the current repo.
+const started = await runtime
+  .query('tools/tool')
+  .withId('session')
+  .resolve();
+
+await started.execute({ action: 'init', workspacePath: '/path/to/repo' });
+
+// Inspect current state (the default action).
+await started.execute({ action: 'status' });
+
+// Pause / resume / archive.
+await started.execute({ action: 'pause' });
+await started.execute({ action: 'resume', sessionId: '<session-id>' });
+await started.execute({ action: 'archive', sessionId: '<session-id>' });
+:::
+
+| Action | Purpose |
+|--------|---------|
+| \`init\` | Create or attach a session; returns a compact bind receipt pointing at \`packet\` |
+| \`get\` | Fetch a session by id |
+| \`status\` | Current active-session state (default) |
+| \`context\` | Hydrated working context for the active session |
+| \`packet\` | Read-only resume packet: roster, assigned/blocked todos, handoff notes, unread |
+| \`list\` | Enumerate this participant's sessions |
+| \`search\` | Search sessions by text/metadata |
+| \`update\` | Mutate session metadata |
+| \`pause\` / \`resume\` | Toggle active state (\`resume\` is lifecycle activation, not the read packet) |
+| \`archive\` | Retire a session to read-only history |
+| \`snapshot\` | Capture a point-in-time snapshot |
+
+### Init vs packet
+
+\`init\` is a **bind receipt**, not an onboarding guide. It returns session/participant
+identity, dynamic capability notices (LSP/Atlas/knowledge/workspace), and a single
+machine-readable \`nextAction\` of \`{ tool: "session", action: "packet" }\`. Static
+coordination tips (claim todos, hand off via collaborate+assign, scratchpad notes,
+knowledge contribution) live in this docs surface and in \`COORDINATION_TIPS\` —
+they are **not** re-emitted on every init.
+
+A default \`init\` only binds. Language services, the Atlas refresh and knowledge
+resolution report \`deferred\`, and the receipt carries a \`preparationAction\` of
+\`{ tool: "session", action: "init", sessionId, prepare: true }\`; pass
+\`prepare: true\` (a \`knowledgeBindingPolicy: "required"\` init always prepares) to
+run them during init. The project and workspace come from the serving runtime,
+never from the \`projectId\` or \`workspacePath\` arguments.
+
+The receipt preserves the declared agent, provider and model identity. Legacy stored
+client info is read per field: malformed optional fields are omitted, and a record
+without a client name supplies no client identity.
+
+After bind, call \`session { action: "packet" }\` to hydrate:
+
+- membership roster (live leases)
+- assigned + unassigned + blocked todos for the caller (other participants' active
+  todos are filtered out; each todo entry includes \`assignedParticipant\`)
+- selected handoff note bodies
+- unread messages for the caller
+
+> The consumer slice registers \`init\` with workspace services resolved through
+> the runtime. The cloud slice registers a typed refusal:
+> \`UNAVAILABLE\` / \`session-init-consumer-required\`. The runtime selects the
+> variant by declared scope; cloud and browser graphs contain no consumer loader.
+
+## Persistence
+
+Session data persists through eleven storage descriptors. The active-session
+pointer and per-participant mappings live in body-scoped \`session.state\` rows;
+the remaining records (sessions, todos, scratchpad, messages, participants,
+presence, connections, jobs, knowledge-refs) are individual
+\`storage/record\` descriptors. See \`session.state\`.
+
+## CLI
+
+The consumer/CLI slices' three \`cli/group\` descriptors expose the tools on the command line:
+
+| Group | Commands |
+|-------|----------|
+| \`session\` | init, list, status, pause, resume, archive, search, chat, jobs, participants, tui |
+| \`session.todo\` | add, complete, list, tree, update |
+| \`session.scratchpad\` (alias \`scratch\`) | write, read, list, search |
+
+:::usage{language="bash"}
+vibes session init --workspace-path .
+vibes session status
+vibes session todo add "Ship the fix"
+vibes session scratchpad write notes "handoff context"
+:::
+
+## Related topics
+
+:::descriptor{kind="docs/topic" id="session.state"}
+:::
+
+:::descriptor{kind="docs/topic" id="session.todo"}
+:::
+
+:::descriptor{kind="docs/topic" id="session.scratchpad"}
+:::
+
+:::descriptor{kind="docs/topic" id="session.collaborate"}
+:::
+`;
+const sessionTopic = {
+    kind: 'docs/topic',
+    id: 'session',
+    title: 'Session',
+    summary: 'Participant sessions — lifecycle, persistent context, todos, scratchpad, collaboration, and paired workspaces',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: sessionOverviewMarkdown
+    },
+    order: 1,
+    tags: ['session', 'lifecycle', 'context', 'dev-workflow'],
+    surfaces: ['cli', 'web', 'in-app', 'mcp'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+// -- child: session.state ----------------------------------------------------
+const sessionStateMarkdown = `---
+title: Session State & Storage
+summary: The session-state manifest plus the per-session storage records that persist a session
+tags: [session, state, storage, persistence]
+parent: session
+order: 1
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Session State & Storage
+
+Session persistence is split between a single state **manifest** that tracks
+which session is active and a set of per-domain **records**.
+
+## The \`session-state\` manifest
+
+\`storage/manifest\` id \`session-state\` (namespace \`dev:session\`, project
+scope) holds the active-session pointer and the per-participant session map:
+
+:::usage{language="ts"}
+interface SessionStateSnapshot {
+  participantSessions: Record<string, string>; // participantId -> sessionId
+  defaultSessionId: string | null;             // active session
+  updatedAt?: string;
+}
+:::
+
+| Field | Notes |
+|-------|-------|
+| adapters | \`storage.localdb\` (default), \`storage.json\` |
+| json filename | \`session-state.json\` |
+| dataType | \`objects\` |
+| scope | \`project\` |
+
+Resolve it through the runtime:
+
+:::usage{language="ts"}
+import type { VibesRuntime } from '@vibesdotdev/kernel';
+
+// The handed runtime: context.runtime in a command, event.locals.runtime in
+// SvelteKit, the onActivate runtime in a plugin.
+declare const runtime: VibesRuntime;
+const state = await runtime
+  .query('storage/manifest')
+  .withId('session-state')
+  .resolve();
+:::
+
+## The eleven storage descriptors
+
+| Descriptor id | Kind | What it stores |
+|---------------|------|----------------|
+| \`session-state\` | manifest | Active session + participant map (above) |
+| \`session.state\` | record | Key-value state rows (table \`session_state\`) |
+| \`session.sessions\` | record | Session entities |
+| \`session.todo\` | record | Session todo items |
+| \`session.scratchpad\` | record | Scratchpad entries |
+| \`session.messages\` | record | Collaboration messages |
+| \`session.participants\` | record | Session participants |
+| \`session.presence\` | record | Presence/heartbeat |
+| \`session.connections\` | record | Connection bookkeeping |
+| \`session.jobs\` | record | Background jobs |
+| \`session.knowledge-refs\` | record | Linked knowledge references |
+
+Records target \`storage.localdb\` (\`sessions.db\`, project scope) and carry
+their own SQL migrations, so the table set is created on first use.
+
+## See also
+
+:::descriptor{kind="docs/topic" id="session"}
+:::
+`;
+const sessionStateTopic = {
+    kind: 'docs/topic',
+    id: 'session.state',
+    title: 'Session State & Storage',
+    summary: 'The session-state manifest plus the per-session storage records that persist a session',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: sessionStateMarkdown
+    },
+    parent: 'session',
+    order: 1,
+    tags: ['session', 'state', 'storage', 'persistence'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+// -- child: session.todo -----------------------------------------------------
+const sessionTodoMarkdown = `---
+title: Session Todos
+summary: The session-todo tool and todo CLI group — task tracking scoped to the active session
+tags: [session, todo, tasks]
+parent: session
+order: 2
+surfaces: [cli, web, in-app, mcp]
+hardware: [consumer, cloud]
+---
+
+# Session Todos
+
+The \`session-todo\` tool tracks tasks within the active session. It is a
+discriminated \`tools/tool\` (default action \`list\`) requiring the
+\`session/manager\` context.
+
+## Actions
+
+| Action | Purpose |
+|--------|---------|
+| \`add\` | Add a single todo |
+| \`batch-add\` | Add many todos in one call |
+| \`list\` | List todos (default) |
+| \`get\` | Fetch one todo |
+| \`update\` | Mutate a todo |
+| \`complete\` | Mark a todo done |
+| \`tree\` | Render the parent/child todo tree |
+
+:::usage{language="ts"}
+import type { VibesRuntime } from '@vibesdotdev/kernel';
+
+// The handed runtime: context.runtime in a command, event.locals.runtime in
+// SvelteKit, the onActivate runtime in a plugin.
+declare const runtime: VibesRuntime;
+const todo = await runtime
+  .query('tools/tool')
+  .withId('session-todo')
+  .resolve();
+
+await todo.execute({ action: 'add', content: 'Ship the fix' });
+await todo.execute({ action: 'list' });
+// Only todos carrying every listed tag (all-of, exact match).
+await todo.execute({ action: 'list', tags: ['kernel-plan'] });
+:::
+
+## CLI
+
+The \`session.todo\` CLI group (parent \`session\`) exposes:
+
+:::usage{language="bash"}
+vibes session todo add "Ship the fix"
+vibes session todo list
+vibes session todo list --tags kernel-plan
+vibes session todo tree
+vibes session todo update <id> --content "Reworded"
+vibes session todo complete <id>
+:::
+
+Todos persist via the \`session.todo\` storage record. See \`session.state\`.
+
+## See also
+
+:::descriptor{kind="docs/topic" id="session"}
+:::
+`;
+const sessionTodoTopic = {
+    kind: 'docs/topic',
+    id: 'session.todo',
+    title: 'Session Todos',
+    summary: 'The session-todo tool and todo CLI group — task tracking scoped to the active session',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: sessionTodoMarkdown
+    },
+    parent: 'session',
+    order: 2,
+    tags: ['session', 'todo', 'tasks'],
+    surfaces: ['cli', 'web', 'in-app', 'mcp'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+// -- child: session.scratchpad -----------------------------------------------
+const sessionScratchpadMarkdown = `---
+title: Session Scratchpad
+summary: The session-scratchpad tool and scratchpad CLI group — free-form notes scoped to the active session
+tags: [session, scratchpad, notes]
+parent: session
+order: 3
+surfaces: [cli, web, in-app, mcp]
+hardware: [consumer, cloud]
+---
+
+# Session Scratchpad
+
+The \`session-scratchpad\` tool stores free-form, keyed notes within the active
+session — handoff context, intermediate findings, anything that should survive
+across turns. It is a discriminated \`tools/tool\` (default action \`list\`)
+requiring the \`session/manager\` context.
+
+## Actions
+
+| Action | Purpose |
+|--------|---------|
+| \`write\` | Write/overwrite a keyed note |
+| \`read\` | Read a note by key |
+| \`list\` | List note keys (default) |
+| \`search\` | Full-text search across notes |
+
+:::usage{language="ts"}
+import type { VibesRuntime } from '@vibesdotdev/kernel';
+
+// The handed runtime: context.runtime in a command, event.locals.runtime in
+// SvelteKit, the onActivate runtime in a plugin.
+declare const runtime: VibesRuntime;
+const scratch = await runtime
+  .query('tools/tool')
+  .withId('session-scratchpad')
+  .resolve();
+
+await scratch.execute({ action: 'write', key: 'notes', content: 'handoff text' });
+await scratch.execute({ action: 'read', key: 'notes' });
+:::
+
+## CLI
+
+The \`session.scratchpad\` CLI group (parent \`session\`, alias \`scratch\`)
+exposes:
+
+:::usage{language="bash"}
+vibes session scratchpad write notes "handoff context"
+vibes session scratchpad read notes
+vibes session scratchpad list
+vibes session scratchpad search "handoff"
+:::
+
+Notes persist via the \`session.scratchpad\` storage record. See
+\`session.state\`.
+
+## See also
+
+:::descriptor{kind="docs/topic" id="session"}
+:::
+`;
+const sessionScratchpadTopic = {
+    kind: 'docs/topic',
+    id: 'session.scratchpad',
+    title: 'Session Scratchpad',
+    summary: 'The session-scratchpad tool and scratchpad CLI group — free-form notes scoped to the active session',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: sessionScratchpadMarkdown
+    },
+    parent: 'session',
+    order: 3,
+    tags: ['session', 'scratchpad', 'notes'],
+    surfaces: ['cli', 'web', 'in-app', 'mcp'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+// -- child: session.collaborate ----------------------------------------------
+const sessionCollaborateMarkdown = `---
+title: Session Collaboration & Workspaces
+summary: The session-collaborate and session-workspace tools — cross-participant handoff and paired external directories
+tags: [session, collaboration, messages, workspace]
+parent: session
+order: 4
+surfaces: [cli, web, in-app, mcp]
+hardware: [consumer, cloud]
+---
+
+# Session Collaboration & Workspaces
+
+Two tools cover working *with others* and working *across directories*.
+
+## \`session-collaborate\`
+
+Cross-participant messaging within a session — handoff notes, status pings,
+acknowledgements. Discriminated \`tools/tool\` (default action \`list\`)
+requiring the \`session/manager\` context.
+
+| Action | Purpose |
+|--------|---------|
+| \`send\` | Post a message to the session |
+| \`list\` | List session messages (default) |
+| \`mark-read\` | Mark messages as read |
+
+:::usage{language="ts"}
+import type { VibesRuntime } from '@vibesdotdev/kernel';
+
+// The handed runtime: context.runtime in a command, event.locals.runtime in
+// SvelteKit, the onActivate runtime in a plugin.
+declare const runtime: VibesRuntime;
+const collab = await runtime
+  .query('tools/tool')
+  .withId('session-collaborate')
+  .resolve();
+
+await collab.execute({ action: 'send', content: 'handoff note' });
+await collab.execute({ action: 'list' });
+:::
+
+Messages persist via the \`session.messages\` storage record; participants and
+presence via \`session.participants\` / \`session.presence\`. Membership leases
+and the resume packet are the live roster/read model — see \`session\` topic
+(\`action: "packet"\`).
+
+## Coordination tips (static — not returned by init)
+
+These operational tips used to ship inside every \`session.init\` response. They
+now live here so bind stays a compact receipt:
+
+1. Share the full session boilerplate, current TODO tree, and scratchpad keys before collaborators begin.
+2. Coordinate by pairing \`session-collaborate\` (action: send --toParticipant) with \`session-todo\` (action: update --assignedParticipant) — there is no separate coordinate tool.
+3. Assign tasks with \`session-todo\` (action: update) so ownership stays explicit and reversible.
+4. Capture interim findings in \`session-scratchpad\` (action: write) before transferring responsibility to another participant.
+5. Before handoff, use \`knowledge\` (action: create) to preserve reusable discoveries (facts, examples, instructions) for future contributors.
+6. After \`session.init\`, call \`session { action: "packet" }\` to hydrate roster, your assigned/blocked todos, handoff notes, and unread messages.
+
+## \`session-workspace\`
+
+Pair external directories (e.g. legacy repos) with the active session so tools
+can reach beyond the primary workspace. Discriminated \`tools/tool\`; unlike the
+others it resolves the active session itself rather than requiring
+\`session/manager\` explicitly.
+
+| Action | Purpose |
+|--------|---------|
+| \`pair\` | Attach an external directory to the session |
+| \`unpair\` | Detach a directory |
+| \`list\` | List paired directories |
+
+:::usage{language="ts"}
+const workspace = await runtime
+  .query('tools/tool')
+  .withId('session-workspace')
+  .resolve();
+
+await workspace.execute({ action: 'pair', path: '/path/to/dir', type: 'legacy' });
+await workspace.execute({ action: 'list' });
+:::
+
+## CLI
+
+Collaboration surfaces through the \`session\` group's \`participants\`,
+\`chat\`, and \`jobs\` commands:
+
+:::usage{language="bash"}
+vibes session participants
+vibes session chat
+vibes session jobs
+:::
+
+## See also
+
+:::descriptor{kind="docs/topic" id="session"}
+:::
+`;
+const sessionCollaborateTopic = {
+    kind: 'docs/topic',
+    id: 'session.collaborate',
+    title: 'Session Collaboration & Workspaces',
+    summary: 'The session-collaborate and session-workspace tools — cross-participant handoff and paired external directories',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: sessionCollaborateMarkdown
+    },
+    parent: 'session',
+    order: 4,
+    tags: ['session', 'collaboration', 'messages', 'workspace'],
+    surfaces: ['cli', 'web', 'in-app', 'mcp'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export const sessionDocsDescriptors = [
+    sessionTopic,
+    sessionStateTopic,
+    sessionTodoTopic,
+    sessionScratchpadTopic,
+    sessionCollaborateTopic
+];
+export default sessionDocsDescriptors;
+//# sourceMappingURL=session.docs.descriptor.js.map

package/dist/docs/session.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/session.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,+EAA+E;AAE/E,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8K/B,CAAC;AAEF,MAAM,YAAY,GAAwB;IACzC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,SAAS;IACb,KAAK,EAAE,SAAS;IAChB,OAAO,EACN,+GAA+G;IAChH,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,uBAAuB;KAC/B;IACD,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC;IACzD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC;IACzC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,+EAA+E;AAE/E,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwE5B,CAAC;AAEF,MAAM,iBAAiB,GAAwB;IAC9C,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,eAAe;IACnB,KAAK,EAAE,yBAAyB;IAChC,OAAO,EAAE,wFAAwF;IACjG,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,oBAAoB;KAC5B;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC;IACpD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,+EAA+E;AAE/E,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgE3B,CAAC;AAEF,MAAM,gBAAgB,GAAwB;IAC7C,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,cAAc;IAClB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,uFAAuF;IAChG,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,mBAAmB;KAC3B;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC;IAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC;IACzC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,+EAA+E;AAE/E,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4DjC,CAAC;AAEF,MAAM,sBAAsB,GAAwB;IACnD,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EACN,qGAAqG;IACtG,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,yBAAyB;KACjC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,CAAC;IACxC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC;IACzC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,+EAA+E;AAE/E,MAAM,0BAA0B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgGlC,CAAC;AAEF,MAAM,uBAAuB,GAAwB;IACpD,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,qBAAqB;IACzB,KAAK,EAAE,oCAAoC;IAC3C,OAAO,EACN,iHAAiH;IAClH,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,0BAA0B;KAClC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,CAAC;IAC3D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC;IACzC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAA0B;IAC5D,YAAY;IACZ,iBAAiB;IACjB,gBAAgB;IAChB,sBAAsB;IACtB,uBAAuB;CACvB,CAAC;AAEF,eAAe,sBAAsB,CAAC"}

package/dist/events/session.bound.event.descriptor.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `session.bound` — a reusable runtime lifecycle event.
+ *
+ * Fired by a surface (MCP serve, CLI bootstrap, autoloop) once it has bound
+ * (created or adopted) a session for a participant. It is a runtime-native
+ * `runtime/event` — the SAME publish/subscribe machinery the awareness on-tool
+ * hooks use (`runtime/src/hooks/` + the `tools.tool.*` event
+ * descriptors) — so a single emit propagates to every interested slice (scope
+ * publish, awareness turn.start) with NO per-harness code.
+ *
+ * `emitSessionBound` commits the session and caller participant identity as
+ * the runtime's bound invocation actor synchronously before hook fanout. A
+ * declared scope carries no identity (RC01 Q4): the kernel starts each later
+ * outermost invocation from the bound actor, so readers see the bind as
+ * `runtime.scope.actor.sessionId` / `.participantId`. Subscribers
+ * (each a `runtime/subscription`, wired
+ * generically by the hooks
+ * wirer):
+ *   - `session.subscriptions.on-session-bound-scope` (this package) — records
+ *     the binding in the session registry, the ONE canonical bound-session
+ *     location, so `brain.pulse` stops falling back to `sessionId:"ephemeral"`.
+ *   - `awareness.hooks.on-session-bound` (awareness) — emits a `turn.start`
+ *     awareness event.
+ *
+ * The wirer maps `{ source: 'session', id: 'session.bound' }` to the bus
+ * `runtime.hooks('session').on('bound', …)`; `emitSessionBound` publishes to
+ * the matching `runtime.hooks('session').emit('bound', …)`.
+ */
+import { z } from 'zod/v4';
+import { VibesRuntime } from '@vibesdotdev/kernel';
+/** Hook-bus namespace the wirer derives from the event `source`. */
+export declare const SESSION_BOUND_NAMESPACE = "session";
+/** Hook-bus event name the wirer derives from the trailing id segment. */
+export declare const SESSION_BOUND_EVENT_NAME = "bound";
+/** Runtime/event descriptor id (subscriptions reference this in `event`). */
+export declare const SESSION_BOUND_EVENT_ID = "session.bound";
+/**
+ * Payload carried on the `session.bound` bus event.
+ *
+ * `runtime` rides the payload exactly like the `tools/tool` hook events
+ * (`{ toolId, callId, input, runtime, metadata }`), so subscribers act on the
+ * same runtime instance the surface bound — no guessing which
+ * runtime to act on, and parallel runtimes stay isolated.
+ */
+export declare const SessionBoundEventSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    participantId: z.ZodOptional<z.ZodString>;
+    surface: z.ZodString;
+    runtime: z.ZodInstanceOf<VibesRuntime>;
+    bindingScope: z.ZodOptional<z.ZodEnum<{
+        request: "request";
+        ambient: "ambient";
+    }>>;
+    reused: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SessionBoundEvent = z.infer<typeof SessionBoundEventSchema>;
+export declare const sessionBoundEvent: {
+    kind: "runtime/event";
+    id: string;
+    source: string;
+    name: string;
+    description: string;
+    trigger: string;
+};
+/** One seat's bound session, as the session registry holds it. */
+export interface RuntimeSessionBinding {
+    sessionId: string;
+    participantId?: string;
+}
+/**
+ * Commit the canonical session identity as the runtime's bound invocation
+ * actor (the kernel's one-seat binding: every outermost invocation starts from
+ * it, and a caller's own actor fields win). It is identity, so it never enters
+ * the declared scope.
+ *
+ * This is synchronous and idempotent by design: hook fanout is useful for
+ * awareness and surface-specific rebinding, but a missing or failing
+ * subscriber must never leave the caller on its previous session.
+ */
+export declare function bindRuntimeSessionScope(runtime: VibesRuntime, sessionId: string, participantId?: string): void;
+/** The session this runtime is bound to, or null when none is bound. */
+export declare function runtimeSessionBinding(runtime: VibesRuntime): RuntimeSessionBinding | null;
+/**
+ * Publish `session.bound` onto the runtime hook bus.
+ *
+ * Surfaces call this AFTER their (surface-specific) create-or-adopt. The hooks
+ * wirer has already bound the scope-publish + turn.start subscriptions to this
+ * namespace/event, so the single emit fans out runtime-natively.
+ */
+export declare function emitSessionBound(event: SessionBoundEvent): Promise<void>;
+export declare const sessionEventDescriptors: readonly [{
+    kind: "runtime/event";
+    id: string;
+    source: string;
+    name: string;
+    description: string;
+    trigger: string;
+}];
+export default sessionBoundEvent;
+//# sourceMappingURL=session.bound.event.descriptor.d.ts.map