@pellux/goodvibes-sdk 0.38.0 → 1.0.0

package/dist/platform/control-plane/method-catalog-control-companion.js

@@ -0,0 +1,133 @@
+import { BOOLEAN_SCHEMA, EMPTY_OBJECT_SCHEMA, NUMBER_SCHEMA, STRING_SCHEMA, arraySchema, bodyEnvelopeSchema, methodDescriptor, objectSchema, } from './method-catalog-shared.js';
+import { COMPANION_CHAT_MESSAGES_LIST_SCHEMA, COMPANION_CHAT_SESSION_SCHEMA, COMPANION_CHAT_SESSIONS_LIST_SCHEMA, COMPANION_CHAT_SESSION_WITH_MESSAGES_SCHEMA, } from './operator-contract-schemas.js';
+export const builtinGatewayControlCompanionMethodDescriptors = [
+    methodDescriptor({
+        id: 'companion.chat.sessions.create',
+        title: 'Create Companion Chat Session',
+        description: 'Create a new companion-chat session. Optional `provider` / `model` override the registry default; `title` and `systemPrompt` are stored on the session record.',
+        category: 'companion',
+        scopes: ['write:sessions'],
+        http: { method: 'POST', path: '/api/companion/chat/sessions' },
+        inputSchema: bodyEnvelopeSchema({
+            title: STRING_SCHEMA,
+            model: STRING_SCHEMA,
+            provider: STRING_SCHEMA,
+            systemPrompt: STRING_SCHEMA,
+        }, []),
+        outputSchema: objectSchema({
+            sessionId: STRING_SCHEMA,
+            createdAt: NUMBER_SCHEMA,
+            session: COMPANION_CHAT_SESSION_SCHEMA,
+        }, ['sessionId', 'createdAt', 'session']),
+    }),
+    methodDescriptor({
+        id: 'companion.chat.sessions.list',
+        title: 'List Companion Chat Sessions',
+        description: 'List active companion-chat sessions. Pass `includeClosed` to include recently closed sessions.',
+        category: 'companion',
+        scopes: ['read:sessions'],
+        http: { method: 'GET', path: '/api/companion/chat/sessions' },
+        inputSchema: objectSchema({
+            includeClosed: BOOLEAN_SCHEMA,
+            limit: NUMBER_SCHEMA,
+        }, []),
+        outputSchema: COMPANION_CHAT_SESSIONS_LIST_SCHEMA,
+    }),
+    methodDescriptor({
+        id: 'companion.chat.sessions.get',
+        title: 'Get Companion Chat Session',
+        description: 'Return a companion-chat session record together with its full message history.',
+        category: 'companion',
+        scopes: ['read:sessions'],
+        http: { method: 'GET', path: '/api/companion/chat/sessions/{sessionId}' },
+        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
+        outputSchema: COMPANION_CHAT_SESSION_WITH_MESSAGES_SCHEMA,
+    }),
+    methodDescriptor({
+        id: 'companion.chat.sessions.update',
+        title: 'Update Companion Chat Session',
+        description: 'Update companion-chat session metadata, including session-local `provider` and `model`, without changing the daemon/TUI current model.',
+        category: 'companion',
+        scopes: ['write:sessions'],
+        http: { method: 'PATCH', path: '/api/companion/chat/sessions/{sessionId}' },
+        inputSchema: bodyEnvelopeSchema({
+            title: STRING_SCHEMA,
+            model: STRING_SCHEMA,
+            provider: STRING_SCHEMA,
+            systemPrompt: STRING_SCHEMA,
+        }, []),
+        outputSchema: objectSchema({
+            session: COMPANION_CHAT_SESSION_SCHEMA,
+        }, ['session']),
+    }),
+    methodDescriptor({
+        id: 'companion.chat.sessions.close',
+        title: 'Close Companion Chat Session',
+        description: 'Close a companion-chat session (soft close). The session record and its messages are preserved in closed state and remain listable with includeClosed. Distinct from companion.chat.sessions.delete, which permanently removes the record.',
+        category: 'companion',
+        scopes: ['write:sessions'],
+        http: { method: 'POST', path: '/api/companion/chat/sessions/{sessionId}/close' },
+        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
+        outputSchema: objectSchema({
+            sessionId: STRING_SCHEMA,
+            status: STRING_SCHEMA,
+        }, ['sessionId', 'status']),
+    }),
+    methodDescriptor({
+        id: 'companion.chat.sessions.delete',
+        title: 'Delete Companion Chat Session',
+        description: 'Permanently remove a companion-chat session: the on-disk record file is deleted and the session is dropped from the shared session store — this does NOT merely close it (use companion.chat.sessions.close for a soft close). Requires the session to already be closed: deleting a still-active session is rejected with 409 SESSION_ACTIVE (close it, then delete). An unknown or already-deleted id is a 404 SESSION_NOT_FOUND, never a 200-noop.',
+        category: 'companion',
+        scopes: ['write:sessions'],
+        http: { method: 'DELETE', path: '/api/companion/chat/sessions/{sessionId}' },
+        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
+        outputSchema: objectSchema({
+            sessionId: STRING_SCHEMA,
+            deleted: BOOLEAN_SCHEMA,
+        }, ['sessionId', 'deleted']),
+    }),
+    methodDescriptor({
+        id: 'companion.chat.messages.create',
+        title: 'Send Companion Chat Message',
+        description: 'Post a user message to a companion-chat session. Accepts either `body` or `content` in the payload; `body` wins when both are provided. Attachments reference artifacts created through `artifacts.create`.',
+        category: 'companion',
+        scopes: ['write:sessions'],
+        http: { method: 'POST', path: '/api/companion/chat/sessions/{sessionId}/messages' },
+        inputSchema: bodyEnvelopeSchema({
+            body: STRING_SCHEMA,
+            content: STRING_SCHEMA,
+            attachments: arraySchema(objectSchema({
+                artifactId: STRING_SCHEMA,
+                label: STRING_SCHEMA,
+                metadata: objectSchema({}, []),
+            }, ['artifactId'])),
+            metadata: objectSchema({}, []),
+        }, []),
+        outputSchema: objectSchema({
+            messageId: STRING_SCHEMA,
+        }, ['messageId']),
+    }),
+    methodDescriptor({
+        id: 'companion.chat.messages.list',
+        title: 'List Companion Chat Messages',
+        description: 'Return the message list for a companion-chat session.',
+        category: 'companion',
+        scopes: ['read:sessions'],
+        http: { method: 'GET', path: '/api/companion/chat/sessions/{sessionId}/messages' },
+        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
+        outputSchema: COMPANION_CHAT_MESSAGES_LIST_SCHEMA,
+    }),
+    methodDescriptor({
+        id: 'companion.chat.events.stream',
+        title: 'Stream Companion Chat Events',
+        description: 'Server-Sent Events stream of turn and agent events scoped to a single companion-chat session.',
+        category: 'companion',
+        scopes: ['read:sessions'],
+        transport: ['http'],
+        http: { method: 'GET', path: '/api/companion/chat/sessions/{sessionId}/events' },
+        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
+        outputSchema: EMPTY_OBJECT_SCHEMA,
+        invokable: false,
+        metadata: { responseKind: 'sse', stream: true, wireEventPrefix: 'companion-chat.' },
+    }),
+];

package/dist/platform/control-plane/method-catalog-control-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"method-catalog-control-core.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/method-catalog-control-core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AA4D1E,eAAO,MAAM,0CAA0C,EAAE,SAAS,uBAAuB,EAunBxF,CAAC"}
+{"version":3,"file":"method-catalog-control-core.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/method-catalog-control-core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AA4D1E,eAAO,MAAM,0CAA0C,EAAE,SAAS,uBAAuB,EAqmBxF,CAAC"}

package/dist/platform/control-plane/method-catalog-control-core.js

@@ -1,5 +1,5 @@
-import { BOOLEAN_SCHEMA, EMPTY_OBJECT_SCHEMA, NUMBER_SCHEMA, STRING_SCHEMA, arraySchema, actionResultOutputSchema, bodyEnvelopeSchema, entityOutputSchema, listOutputSchema, methodDescriptor, objectSchema, runtimeEventId, METHOD_DESCRIPTOR_SCHEMA, EVENT_DESCRIPTOR_SCHEMA, } from './method-catalog-shared.js';
-import { APPROVAL_ACTION_INPUT_SCHEMA, APPROVAL_ACTION_OUTPUT_SCHEMA, APPROVAL_SNAPSHOT_SCHEMA, COMPANION_CHAT_MESSAGES_LIST_SCHEMA, COMPANION_CHAT_SESSION_SCHEMA, COMPANION_CHAT_SESSIONS_LIST_SCHEMA, COMPANION_CHAT_SESSION_WITH_MESSAGES_SCHEMA, CONTROL_AUTH_CURRENT_RESPONSE_SCHEMA, CONTROL_AUTH_LOGIN_REQUEST_SCHEMA, CONTROL_AUTH_LOGIN_RESPONSE_SCHEMA, CONTROL_PLANE_CLIENT_DESCRIPTOR_SCHEMA, CONTROL_PLANE_SURFACE_MESSAGE_SCHEMA, CONTROL_PLANE_SNAPSHOT_SCHEMA, OTLP_LOG_DOCUMENT_SCHEMA, OTLP_METRIC_DOCUMENT_SCHEMA, OTLP_TRACE_DOCUMENT_SCHEMA, REVIEW_SNAPSHOT_SCHEMA, SESSION_BROKER_SNAPSHOT_SCHEMA, SESSION_SNAPSHOT_SCHEMA, SHARED_SESSION_CREATE_OUTPUT_SCHEMA, SHARED_SESSION_INPUT_RECORD_SCHEMA, SHARED_SESSION_MESSAGE_CREATE_OUTPUT_SCHEMA, SHARED_SESSION_MESSAGE_ROUTE_OUTPUT_SCHEMA, SHARED_SESSION_RECORD_SCHEMA, SHARED_SESSION_ROUTING_INTENT_SCHEMA, SHARED_SESSION_WITH_INPUTS_SCHEMA, SHARED_SESSION_WITH_MESSAGES_SCHEMA, TASK_ACTION_OUTPUT_SCHEMA, TASK_CREATE_INPUT_SCHEMA, TASK_CREATE_OUTPUT_SCHEMA, TASK_OUTPUT_SCHEMA, TASK_SNAPSHOT_SCHEMA, TASK_STATUS_OUTPUT_SCHEMA, TELEMETRY_FILTER_INPUT_SCHEMA, TELEMETRY_METRICS_SNAPSHOT_SCHEMA, TELEMETRY_RECORD_LIST_RESPONSE_SCHEMA, TELEMETRY_SNAPSHOT_SCHEMA, TELEMETRY_SPAN_LIST_RESPONSE_SCHEMA, TELEMETRY_STREAM_READY_SCHEMA, } from './operator-contract-schemas.js';
+import { BOOLEAN_SCHEMA, EMPTY_OBJECT_SCHEMA, NUMBER_SCHEMA, STRING_SCHEMA, actionResultOutputSchema, bodyEnvelopeSchema, entityOutputSchema, listOutputSchema, methodDescriptor, objectSchema, runtimeEventId, METHOD_DESCRIPTOR_SCHEMA, EVENT_DESCRIPTOR_SCHEMA, } from './method-catalog-shared.js';
+import { APPROVAL_ACTION_INPUT_SCHEMA, APPROVAL_APPROVE_INPUT_SCHEMA, APPROVAL_ACTION_OUTPUT_SCHEMA, APPROVAL_SNAPSHOT_SCHEMA, CONTROL_AUTH_CURRENT_RESPONSE_SCHEMA, CONTROL_AUTH_LOGIN_REQUEST_SCHEMA, CONTROL_AUTH_LOGIN_RESPONSE_SCHEMA, CONTROL_PLANE_CLIENT_DESCRIPTOR_SCHEMA, CONTROL_PLANE_SURFACE_MESSAGE_SCHEMA, CONTROL_PLANE_SNAPSHOT_SCHEMA, SESSIONS_SEARCH_INPUT_SCHEMA, SESSIONS_SEARCH_OUTPUT_SCHEMA, OTLP_LOG_DOCUMENT_SCHEMA, OTLP_METRIC_DOCUMENT_SCHEMA, OTLP_TRACE_DOCUMENT_SCHEMA, REVIEW_SNAPSHOT_SCHEMA, SESSION_BROKER_SNAPSHOT_SCHEMA, SESSION_SNAPSHOT_SCHEMA, SHARED_SESSION_CREATE_OUTPUT_SCHEMA, SHARED_SESSION_INPUT_RECORD_SCHEMA, SHARED_SESSION_MESSAGE_CREATE_OUTPUT_SCHEMA, SHARED_SESSION_MESSAGE_ROUTE_OUTPUT_SCHEMA, SHARED_SESSION_RECORD_SCHEMA, SHARED_SESSION_REGISTER_INPUT_SCHEMA, SHARED_SESSION_REGISTER_OUTPUT_SCHEMA, SHARED_SESSION_ROUTING_INTENT_SCHEMA, SHARED_SESSION_WITH_INPUTS_SCHEMA, SHARED_SESSION_WITH_MESSAGES_SCHEMA, TASK_ACTION_OUTPUT_SCHEMA, TASK_CREATE_INPUT_SCHEMA, TASK_CREATE_OUTPUT_SCHEMA, TASK_OUTPUT_SCHEMA, TASK_SNAPSHOT_SCHEMA, TASK_STATUS_OUTPUT_SCHEMA, TELEMETRY_FILTER_INPUT_SCHEMA, TELEMETRY_METRICS_SNAPSHOT_SCHEMA, TELEMETRY_RECORD_LIST_RESPONSE_SCHEMA, TELEMETRY_SNAPSHOT_SCHEMA, TELEMETRY_SPAN_LIST_RESPONSE_SCHEMA, TELEMETRY_STREAM_READY_SCHEMA, } from './operator-contract-schemas.js';
 import { OPERATOR_CONTRACT_SCHEMA } from './operator-contract.js';
 export const builtinGatewayControlCoreMethodDescriptors = [
     methodDescriptor({
@@ -280,6 +280,7 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         category: 'sessions',
         scopes: ['write:sessions'],
         http: { method: 'POST', path: '/api/sessions' },
+        events: ['control.session_update'],
         inputSchema: bodyEnvelopeSchema({
             title: STRING_SCHEMA,
             surfaceKind: STRING_SCHEMA,
@@ -287,6 +288,17 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         }),
         outputSchema: SHARED_SESSION_CREATE_OUTPUT_SCHEMA,
     }),
+    methodDescriptor({
+        id: 'sessions.register',
+        title: 'Register Shared Session',
+        description: 'Idempotently register (or heartbeat) a session keyed on a caller-supplied id, carrying its kind, project, and participant identity. Re-calling with the same id advances the participant lastSeenAt (heartbeat). Registering against a CLOSED session does NOT silently reopen it — the heartbeat is recorded and the still-closed record is returned with reopened=false and conflict={status:closed}; pass reopen=true to reopen. A titled session is never renamed by the heartbeat. An unknown kind is rejected (400), not coerced. Prefer this over sessions.create for external runtimes that own their session id.',
+        category: 'sessions',
+        scopes: ['write:sessions'],
+        http: { method: 'POST', path: '/api/sessions/register' },
+        events: ['control.session_update'],
+        inputSchema: SHARED_SESSION_REGISTER_INPUT_SCHEMA,
+        outputSchema: SHARED_SESSION_REGISTER_OUTPUT_SCHEMA,
+    }),
     methodDescriptor({
         id: 'sessions.get',
         title: 'Get Shared Session',
@@ -304,6 +316,7 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         category: 'sessions',
         scopes: ['write:sessions'],
         http: { method: 'POST', path: '/api/sessions/{sessionId}/close' },
+        events: ['control.session_update'],
         inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
         outputSchema: actionResultOutputSchema('session', SHARED_SESSION_RECORD_SCHEMA),
     }),
@@ -314,9 +327,38 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         category: 'sessions',
         scopes: ['write:sessions'],
         http: { method: 'POST', path: '/api/sessions/{sessionId}/reopen' },
+        events: ['control.session_update'],
         inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
         outputSchema: actionResultOutputSchema('session', SHARED_SESSION_RECORD_SCHEMA),
     }),
+    methodDescriptor({
+        id: 'sessions.detach',
+        title: 'Detach Shared Session Participant',
+        description: 'Remove a surface\'s participant and its route binding from a session so that surface stops receiving updates, WITHOUT closing or killing the session (detach != close != kill). Every participant carrying the given surfaceId is removed and any route binding they alone held is unbound; the session and all other participants keep running. Idempotent: detaching an already-detached surface, or detaching from a closed session, is a no-op success. An unknown session is a 404.',
+        category: 'sessions',
+        scopes: ['write:sessions'],
+        http: { method: 'POST', path: '/api/sessions/{sessionId}/detach' },
+        events: ['control.session_update'],
+        inputSchema: objectSchema({
+            sessionId: STRING_SCHEMA,
+            surfaceId: STRING_SCHEMA,
+        }, ['sessionId', 'surfaceId']),
+        outputSchema: actionResultOutputSchema('session', SHARED_SESSION_RECORD_SCHEMA),
+    }),
+    methodDescriptor({
+        id: 'sessions.delete',
+        title: 'Delete Shared Session',
+        description: 'Permanently remove a shared session record and its queued inputs/messages from the home-scoped store. A distinct, explicit hard-delete verb — NEVER triggered by close; closed sessions stay listable (includeClosed) and deletionRetentionMs semantics for non-deleted records are untouched. Requires the session to already be closed: deleting a still-active session is rejected with 409 SESSION_ACTIVE (close it, then delete). An unknown or already-deleted id is a 404 SESSION_NOT_FOUND, never a 200-noop. Emits control.session_update (session-deleted) so subscribers drop the row live.',
+        category: 'sessions',
+        scopes: ['write:sessions'],
+        http: { method: 'DELETE', path: '/api/sessions/{sessionId}' },
+        events: ['control.session_update'],
+        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
+        outputSchema: objectSchema({
+            sessionId: STRING_SCHEMA,
+            deleted: BOOLEAN_SCHEMA,
+        }, ['sessionId', 'deleted']),
+    }),
     methodDescriptor({
         id: 'sessions.messages.list',
         title: 'List Shared Session Messages',
@@ -338,6 +380,7 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         category: 'sessions',
         scopes: ['write:sessions'],
         http: { method: 'POST', path: '/api/sessions/{sessionId}/messages' },
+        events: ['control.session_update'],
         inputSchema: bodyEnvelopeSchema({
             body: STRING_SCHEMA,
             surfaceKind: STRING_SCHEMA,
@@ -350,13 +393,15 @@ export const builtinGatewayControlCoreMethodDescriptors = [
     methodDescriptor({
         id: 'sessions.inputs.list',
         title: 'List Shared Session Inputs',
-        description: 'Return explicit session inputs, including queued follow-ups and delivered steering requests.',
+        description: 'Return explicit session inputs, including queued follow-ups and delivered steering requests. A live surface collects work by filtering `state` (e.g. queued) and paging past a `since` createdAt cursor (exclusive), draining only inputs it has not yet collected.',
         category: 'sessions',
         scopes: ['read:sessions'],
         http: { method: 'GET', path: '/api/sessions/{sessionId}/inputs' },
         inputSchema: objectSchema({
             sessionId: STRING_SCHEMA,
             limit: NUMBER_SCHEMA,
+            state: STRING_SCHEMA,
+            since: NUMBER_SCHEMA,
         }, ['sessionId']),
         outputSchema: SHARED_SESSION_WITH_INPUTS_SCHEMA,
     }),
@@ -367,6 +412,7 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         category: 'sessions',
         scopes: ['write:sessions'],
         http: { method: 'POST', path: '/api/sessions/{sessionId}/steer' },
+        events: ['control.session_update'],
         inputSchema: bodyEnvelopeSchema({
             body: STRING_SCHEMA,
             surfaceKind: STRING_SCHEMA,
@@ -383,6 +429,7 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         category: 'sessions',
         scopes: ['write:sessions'],
         http: { method: 'POST', path: '/api/sessions/{sessionId}/follow-up' },
+        events: ['control.session_update'],
         inputSchema: bodyEnvelopeSchema({
             body: STRING_SCHEMA,
             surfaceKind: STRING_SCHEMA,
@@ -398,12 +445,60 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         category: 'sessions',
         scopes: ['write:sessions'],
         http: { method: 'POST', path: '/api/sessions/{sessionId}/inputs/{inputId}/cancel' },
+        events: ['control.session_update'],
         inputSchema: objectSchema({
             sessionId: STRING_SCHEMA,
             inputId: STRING_SCHEMA,
         }, ['sessionId', 'inputId']),
         outputSchema: entityOutputSchema('input', SHARED_SESSION_INPUT_RECORD_SCHEMA),
     }),
+    methodDescriptor({
+        id: 'sessions.inputs.deliver',
+        title: 'Mark Shared Session Input Delivered',
+        description: 'A live registered surface reports that it collected a queued input (moves it to `delivered`) or finished acting on it (`consumed:true` moves it to `completed`). This is how a surface-managed session — where steer/follow-up inputs queue for the surface rather than spawn a daemon executor — closes the input lifecycle honestly. Only queued/delivered inputs advance; others are returned unchanged.',
+        category: 'sessions',
+        scopes: ['write:sessions'],
+        http: { method: 'POST', path: '/api/sessions/{sessionId}/inputs/{inputId}/deliver' },
+        events: ['control.session_update'],
+        inputSchema: objectSchema({
+            sessionId: STRING_SCHEMA,
+            inputId: STRING_SCHEMA,
+            consumed: BOOLEAN_SCHEMA,
+        }, ['sessionId', 'inputId']),
+        outputSchema: entityOutputSchema('input', SHARED_SESSION_INPUT_RECORD_SCHEMA),
+    }),
+    // ── W3-S2: sessions.search ──────────────────────────────────────────────
+    // Paginated/filtered query over the home-scoped session store, extending
+    // the Wave-1 list-filter shape (project/kind/includeClosed) with free-text
+    // `query`, `surfaceKind`, `status`, and opaque cursor pagination. Handler:
+    // routes/session-search.ts (registered directly on the catalog with no
+    // `http` REST binding — see the transport note below).
+    //
+    // TRANSPORT NOTE (applies to sessions.search + the whole fleet.*/
+    // checkpoints.* block below): `transport: ['ws']` with no `http` binding is
+    // the transport-parity gate's (test/transport-parity.test.ts) own
+    // sanctioned category for a catalog method dispatchable ONLY via the
+    // generic invoke-by-id mechanism (`gatewayMethods.hasHandler`/`invoke`,
+    // daemon/control-plane.ts `invokeGatewayMethodCall`) rather than a
+    // dedicated REST path — reachable today over HTTP via
+    // `POST /api/control-plane/methods/{methodId}/invoke` AND over WebSocket
+    // via a `{type:'call', methodId}` frame (both converge on the same
+    // invokeGatewayMethodCall). A typed client wrapper (operator-sdk
+    // client-core.ts's invokeContractRoute, which dispatches by literal
+    // http.method/http.path) is NOT wired for these verbs by this brief —
+    // that is curated, consumer-side work for whichever later stage first
+    // needs a typed wrapper (W1/W2/T2), not a requirement of landing the SDK
+    // contract itself.
+    methodDescriptor({
+        id: 'sessions.search',
+        title: 'Search Shared Sessions',
+        description: 'Paginated, filtered query over shared sessions: free-text query (matches id/title), project, kind, surfaceKind, and status. Closed sessions are EXCLUDED by default — pass includeClosed:true to include them, and a returned closed session always carries an honest status:"closed" (never hidden, never relabeled). Cursor pagination returns disjoint pages that union to the full matching set.',
+        category: 'sessions',
+        scopes: ['read:sessions'],
+        transport: ['ws'],
+        inputSchema: SESSIONS_SEARCH_INPUT_SCHEMA,
+        outputSchema: SESSIONS_SEARCH_OUTPUT_SCHEMA,
+    }),
     methodDescriptor({
         id: 'tasks.list',
         title: 'List Runtime Tasks',
@@ -465,6 +560,10 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         inputSchema: objectSchema({ agentId: STRING_SCHEMA }, ['agentId']),
         outputSchema: TASK_STATUS_OUTPUT_SCHEMA,
     }),
+    // fleet.* + checkpoints.* descriptors moved to method-catalog-fleet.ts
+    // (W3-S2) — this file was already at the 800-line cap; see that file's
+    // header comment for the full design rationale, merged in by
+    // method-catalog-control.ts alongside method-catalog-control-automation.ts.
     methodDescriptor({
         id: 'approvals.list',
         title: 'List Approvals',
@@ -488,11 +587,11 @@ export const builtinGatewayControlCoreMethodDescriptors = [
     methodDescriptor({
         id: 'approvals.approve',
         title: 'Approve Approval',
-        description: 'Approve a pending approval.',
+        description: 'Approve a pending approval. Optionally pass selectedHunks (edit-tool approvals only): the daemon filters the approval\'s own edit list to those hunk indices server-side, so every surface produces identical modified-edit args. Omitting selectedHunks approves the whole request (back-compat). An out-of-range index or a non-edit approval is rejected with a 400.',
         category: 'approvals',
         scopes: ['write:approvals'],
         http: { method: 'POST', path: '/api/approvals/{approvalId}/approve' },
-        inputSchema: APPROVAL_ACTION_INPUT_SCHEMA,
+        inputSchema: APPROVAL_APPROVE_INPUT_SCHEMA,
         outputSchema: APPROVAL_ACTION_OUTPUT_SCHEMA,
     }),
     methodDescriptor({
@@ -515,121 +614,4 @@ export const builtinGatewayControlCoreMethodDescriptors = [
         inputSchema: APPROVAL_ACTION_INPUT_SCHEMA,
         outputSchema: APPROVAL_ACTION_OUTPUT_SCHEMA,
     }),
-    // Companion-chat method catalog registration.
-    methodDescriptor({
-        id: 'companion.chat.sessions.create',
-        title: 'Create Companion Chat Session',
-        description: 'Create a new companion-chat session. Optional `provider` / `model` override the registry default; `title` and `systemPrompt` are stored on the session record.',
-        category: 'companion',
-        scopes: ['write:sessions'],
-        http: { method: 'POST', path: '/api/companion/chat/sessions' },
-        inputSchema: bodyEnvelopeSchema({
-            title: STRING_SCHEMA,
-            model: STRING_SCHEMA,
-            provider: STRING_SCHEMA,
-            systemPrompt: STRING_SCHEMA,
-        }, []),
-        outputSchema: objectSchema({
-            sessionId: STRING_SCHEMA,
-            createdAt: NUMBER_SCHEMA,
-            session: COMPANION_CHAT_SESSION_SCHEMA,
-        }, ['sessionId', 'createdAt', 'session']),
-    }),
-    methodDescriptor({
-        id: 'companion.chat.sessions.list',
-        title: 'List Companion Chat Sessions',
-        description: 'List active companion-chat sessions. Pass `includeClosed` to include recently closed sessions.',
-        category: 'companion',
-        scopes: ['read:sessions'],
-        http: { method: 'GET', path: '/api/companion/chat/sessions' },
-        inputSchema: objectSchema({
-            includeClosed: BOOLEAN_SCHEMA,
-            limit: NUMBER_SCHEMA,
-        }, []),
-        outputSchema: COMPANION_CHAT_SESSIONS_LIST_SCHEMA,
-    }),
-    methodDescriptor({
-        id: 'companion.chat.sessions.get',
-        title: 'Get Companion Chat Session',
-        description: 'Return a companion-chat session record together with its full message history.',
-        category: 'companion',
-        scopes: ['read:sessions'],
-        http: { method: 'GET', path: '/api/companion/chat/sessions/{sessionId}' },
-        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
-        outputSchema: COMPANION_CHAT_SESSION_WITH_MESSAGES_SCHEMA,
-    }),
-    methodDescriptor({
-        id: 'companion.chat.sessions.update',
-        title: 'Update Companion Chat Session',
-        description: 'Update companion-chat session metadata, including session-local `provider` and `model`, without changing the daemon/TUI current model.',
-        category: 'companion',
-        scopes: ['write:sessions'],
-        http: { method: 'PATCH', path: '/api/companion/chat/sessions/{sessionId}' },
-        inputSchema: bodyEnvelopeSchema({
-            title: STRING_SCHEMA,
-            model: STRING_SCHEMA,
-            provider: STRING_SCHEMA,
-            systemPrompt: STRING_SCHEMA,
-        }, []),
-        outputSchema: objectSchema({
-            session: COMPANION_CHAT_SESSION_SCHEMA,
-        }, ['session']),
-    }),
-    methodDescriptor({
-        id: 'companion.chat.sessions.delete',
-        title: 'Close Companion Chat Session',
-        description: 'Close a companion-chat session. The session record is preserved in closed state.',
-        category: 'companion',
-        scopes: ['write:sessions'],
-        http: { method: 'DELETE', path: '/api/companion/chat/sessions/{sessionId}' },
-        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
-        outputSchema: objectSchema({
-            sessionId: STRING_SCHEMA,
-            status: STRING_SCHEMA,
-        }, ['sessionId', 'status']),
-    }),
-    methodDescriptor({
-        id: 'companion.chat.messages.create',
-        title: 'Send Companion Chat Message',
-        description: 'Post a user message to a companion-chat session. Accepts either `body` or `content` in the payload; `body` wins when both are provided. Attachments reference artifacts created through `artifacts.create`.',
-        category: 'companion',
-        scopes: ['write:sessions'],
-        http: { method: 'POST', path: '/api/companion/chat/sessions/{sessionId}/messages' },
-        inputSchema: bodyEnvelopeSchema({
-            body: STRING_SCHEMA,
-            content: STRING_SCHEMA,
-            attachments: arraySchema(objectSchema({
-                artifactId: STRING_SCHEMA,
-                label: STRING_SCHEMA,
-                metadata: objectSchema({}, []),
-            }, ['artifactId'])),
-            metadata: objectSchema({}, []),
-        }, []),
-        outputSchema: objectSchema({
-            messageId: STRING_SCHEMA,
-        }, ['messageId']),
-    }),
-    methodDescriptor({
-        id: 'companion.chat.messages.list',
-        title: 'List Companion Chat Messages',
-        description: 'Return the message list for a companion-chat session.',
-        category: 'companion',
-        scopes: ['read:sessions'],
-        http: { method: 'GET', path: '/api/companion/chat/sessions/{sessionId}/messages' },
-        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
-        outputSchema: COMPANION_CHAT_MESSAGES_LIST_SCHEMA,
-    }),
-    methodDescriptor({
-        id: 'companion.chat.events.stream',
-        title: 'Stream Companion Chat Events',
-        description: 'Server-Sent Events stream of turn and agent events scoped to a single companion-chat session.',
-        category: 'companion',
-        scopes: ['read:sessions'],
-        transport: ['http'],
-        http: { method: 'GET', path: '/api/companion/chat/sessions/{sessionId}/events' },
-        inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
-        outputSchema: EMPTY_OBJECT_SCHEMA,
-        invokable: false,
-        metadata: { responseKind: 'sse', stream: true, wireEventPrefix: 'companion-chat.' },
-    }),
 ];

package/dist/platform/control-plane/method-catalog-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"method-catalog-control.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/method-catalog-control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAI1E,eAAO,MAAM,sCAAsC,EAAE,SAAS,uBAAuB,EAGpF,CAAC"}
+{"version":3,"file":"method-catalog-control.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/method-catalog-control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAM1E,eAAO,MAAM,sCAAsC,EAAE,SAAS,uBAAuB,EAKpF,CAAC"}

package/dist/platform/control-plane/method-catalog-control.js

@@ -1,6 +1,10 @@
 import { builtinGatewayControlAutomationMethodDescriptors } from './method-catalog-control-automation.js';
+import { builtinGatewayControlCompanionMethodDescriptors } from './method-catalog-control-companion.js';
 import { builtinGatewayControlCoreMethodDescriptors } from './method-catalog-control-core.js';
+import { builtinGatewayFleetMethodDescriptors } from './method-catalog-fleet.js';
 export const builtinGatewayControlMethodDescriptors = [
     ...builtinGatewayControlCoreMethodDescriptors,
+    ...builtinGatewayControlCompanionMethodDescriptors,
     ...builtinGatewayControlAutomationMethodDescriptors,
+    ...builtinGatewayFleetMethodDescriptors,
 ];

package/dist/platform/control-plane/method-catalog-email.d.ts

@@ -4,6 +4,23 @@ import type { GatewayMethodDescriptor } from './method-catalog-shared.js';
  * standard operator method protocol so email operations can be triggered via MCP
  * connector actions in addition to the direct-socket path. Daemon-backed; the SDK
  * publishes the typed contract surface (no internal handler).
+ *
+ * W4-A3 (capability-advertisement honesty): none of these four http paths are
+ * currently served by the daemon router — there is no /api/email surface at
+ * any prefix (confirmed by reading router.ts and every dispatch chain it
+ * delegates to; see method-catalog-route-reconcile.ts). The daemon's own 404
+ * handler names an /api/email-vs-/api/v1-shaped skew, but that's a red
+ * herring here: this isn't a path that moved, it's a path that was never
+ * wired to a route or an internal handler at all. Per the "reality wins"
+ * fix (correct the path where the route moved, mark unavailable where no
+ * route exists), these are marked `invokable: false` so the published
+ * contract and the live method-dispatch path both say "cataloged, not
+ * callable" instead of letting a caller discover the 404 the hard way.
+ * Un-mark a method once its real IMAP/SMTP-backed route or handler exists —
+ * the route-reconcile regression gate (method-catalog-route-reconcile.ts,
+ * exercised in test/w4-a3-capability-route-reconcile.test.ts) will catch it
+ * if this comment goes stale and a route reappears without the flag being
+ * cleared, or a new advertise-without-route method slips in unmarked.
  */
 export declare const builtinGatewayEmailMethodDescriptors: readonly GatewayMethodDescriptor[];
 //# sourceMappingURL=method-catalog-email.d.ts.map

package/dist/platform/control-plane/method-catalog-email.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"method-catalog-email.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/method-catalog-email.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAsC1E;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,EAAE,SAAS,uBAAuB,EA0ElF,CAAC"}
+{"version":3,"file":"method-catalog-email.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/method-catalog-email.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAsC1E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,oCAAoC,EAAE,SAAS,uBAAuB,EA8ElF,CAAC"}

package/dist/platform/control-plane/method-catalog-email.js

@@ -28,6 +28,23 @@ const EMAIL_MESSAGE_DETAIL_SCHEMA = objectSchema({
  * standard operator method protocol so email operations can be triggered via MCP
  * connector actions in addition to the direct-socket path. Daemon-backed; the SDK
  * publishes the typed contract surface (no internal handler).
+ *
+ * W4-A3 (capability-advertisement honesty): none of these four http paths are
+ * currently served by the daemon router — there is no /api/email surface at
+ * any prefix (confirmed by reading router.ts and every dispatch chain it
+ * delegates to; see method-catalog-route-reconcile.ts). The daemon's own 404
+ * handler names an /api/email-vs-/api/v1-shaped skew, but that's a red
+ * herring here: this isn't a path that moved, it's a path that was never
+ * wired to a route or an internal handler at all. Per the "reality wins"
+ * fix (correct the path where the route moved, mark unavailable where no
+ * route exists), these are marked `invokable: false` so the published
+ * contract and the live method-dispatch path both say "cataloged, not
+ * callable" instead of letting a caller discover the 404 the hard way.
+ * Un-mark a method once its real IMAP/SMTP-backed route or handler exists —
+ * the route-reconcile regression gate (method-catalog-route-reconcile.ts,
+ * exercised in test/w4-a3-capability-route-reconcile.test.ts) will catch it
+ * if this comment goes stale and a route reappears without the flag being
+ * cleared, or a new advertise-without-route method slips in unmarked.
  */
 export const builtinGatewayEmailMethodDescriptors = [
     methodDescriptor({
@@ -46,6 +63,7 @@ export const builtinGatewayEmailMethodDescriptors = [
             messages: arraySchema(EMAIL_INBOX_MESSAGE_SCHEMA),
             total: NUMBER_SCHEMA,
         }, ['messages', 'total']),
+        invokable: false,
     }),
     methodDescriptor({
         id: 'email.inbox.read',
@@ -56,6 +74,7 @@ export const builtinGatewayEmailMethodDescriptors = [
         http: { method: 'GET', path: '/api/email/inbox/{uid}' },
         inputSchema: objectSchema({ uid: NUMBER_SCHEMA }, ['uid']),
         outputSchema: EMAIL_MESSAGE_DETAIL_SCHEMA,
+        invokable: false,
     }),
     methodDescriptor({
         id: 'email.draft.create',
@@ -77,6 +96,7 @@ export const builtinGatewayEmailMethodDescriptors = [
             draftId: STRING_SCHEMA,
         }, ['uid', 'draftId']),
         dangerous: true,
+        invokable: false,
     }),
     methodDescriptor({
         id: 'email.send',
@@ -98,5 +118,6 @@ export const builtinGatewayEmailMethodDescriptors = [
             sentAt: STRING_SCHEMA,
         }, ['messageId', 'sentAt']),
         dangerous: true,
+        invokable: false,
     }),
 ];

package/dist/platform/control-plane/method-catalog-events.d.ts

@@ -1,3 +1,31 @@
 import type { GatewayEventDescriptor } from './method-catalog-shared.js';
+/**
+ * The discriminated `event` values carried inside every `session-update` wire frame.
+ *
+ * The SharedSessionBroker collapses ALL of its lifecycle signals onto a single wire event
+ * named `session-update` (session-broker.ts `publishUpdate`); the real lifecycle name lives
+ * in the frame's `payload.event` field. This list is the source of truth for that
+ * discriminant and is documented by the `control.session_update` descriptor below so a
+ * subscriber (webui/TUI) can switch on `payload.event` against a contract-backed enum
+ * instead of guessing from undocumented behavior.
+ *
+ * NOTE (One-Platform S1 coordination): new broker signals flow through the SAME
+ * `session-update` wire channel automatically because `publishUpdate` is generic — when
+ * S1's `sessions.register` flow emits e.g. `session-registered`, only THIS enum needs the
+ * added string (the wire channel already carries it). Keep this list aligned with the
+ * broker's publishUpdate/publishInputLifecycleEvent call sites.
+ */
+export declare const SESSION_UPDATE_WIRE_EVENTS: readonly ["session-created", "session-closed", "session-deleted", "session-reopened", "session-agent-bound", "session-agent-completed", "session-message-appended", "session-message-forwarded", "session-route-attached", "session-detached", "session-input-queued", "session-input-queued-for-surface", "session-input-delivered", "session-input-spawned", "session-input-completed", "session-input-failed", "session-input-rejected", "session-input-cancelled", "session-follow-up-queued", "session-follow-up-spawned"];
+/**
+ * Maps each cross-surface invalidation intent to the concrete `payload.event` value(s) a
+ * subscriber must react to. Documented in the descriptor so the webui/TUI do not guess.
+ */
+export declare const SESSION_UPDATE_INTENT_MAP: {
+    readonly created: readonly ["session-created"];
+    readonly updated: readonly ["session-message-appended", "session-agent-completed", "session-route-attached", "session-detached", "session-reopened"];
+    readonly steered: readonly ["session-input-queued-for-surface", "session-input-delivered", "session-message-forwarded"];
+    readonly closed: readonly ["session-closed"];
+    readonly deleted: readonly ["session-deleted"];
+};
 export declare const builtinGatewayEventDescriptors: readonly GatewayEventDescriptor[];
 //# sourceMappingURL=method-catalog-events.d.ts.map

package/dist/platform/control-plane/method-catalog-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"method-catalog-events.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/method-catalog-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAmCzE,eAAO,MAAM,8BAA8B,EAAE,SAAS,sBAAsB,EAuC3E,CAAC"}
+{"version":3,"file":"method-catalog-events.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/method-catalog-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAKzE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,0BAA0B,igBAqB7B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;CAMqD,CAAC;AAgC5F,eAAO,MAAM,8BAA8B,EAAE,SAAS,sBAAsB,EAgE3E,CAAC"}