@openchamber/sdk 2.5.3 → 2.6.0

package/dist/service-providers.js

@@ -143,7 +143,8 @@ export const sourceControlProviderTimeoutMs = (method) => {
 /**
  * Environment variable with the base URL of OpenChamber's callback listener
  * (`http://127.0.0.1:<port>`). Set only for a service that provides
- * `source-control`; `createSourceControlForge` reads it.
+ * `source-control`, `notifications` or `tracker`; `createSourceControlForge`,
+ * `createNotificationsOutbound` and `createTrackerOutbound` read it.
  */
 export const OPENCHAMBER_HOST_CALLBACK_URL = 'OPENCHAMBER_HOST_CALLBACK_URL';
 /** Route on the callback listener a service sends a forge request to. */
@@ -237,6 +238,48 @@ export class SourceControlForgeError extends Error {
         this.status = status;
     }
 }
+/**
+ * One request through OpenChamber's callback listener: the handle as bearer,
+ * the request as JSON, the relayed answer back. `fail` makes the role's own
+ * error for a refusal, a silent host or a malformed relay; an answer of any
+ * status from the far side, 401 included, resolves.
+ */
+const postOutbound = async (url, handle, request, timeoutMs, fail) => {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${handle}`, 'content-type': 'application/json' },
+            body: JSON.stringify(request),
+            // A little past OpenChamber's own deadline, so its answer wins.
+            signal: AbortSignal.timeout(timeoutMs + 5_000),
+        });
+    }
+    catch (error) {
+        throw fail(`OpenChamber did not answer: ${error instanceof Error ? error.message : String(error)}`, 'HOST_UNAVAILABLE', 0);
+    }
+    let answer;
+    try {
+        answer = Object(await response.json());
+    }
+    catch {
+        throw fail('OpenChamber answered with something other than JSON', 'HOST_UNAVAILABLE', response.status);
+    }
+    if (!response.ok) {
+        const message = answer.error?.message;
+        const code = answer.error?.code;
+        throw fail(String(message) === message && message.length > 0 ? message : `OpenChamber refused the request (${response.status})`, String(code) === code && code.length > 0 ? code : 'OUTBOUND_REFUSED', response.status);
+    }
+    if (!Number.isSafeInteger(answer.status) || String(answer.body) !== answer.body) {
+        throw fail('OpenChamber relayed a malformed answer', 'HOST_UNAVAILABLE', response.status);
+    }
+    const headers = {};
+    for (const [name, text] of Object.entries(Object(answer.headers ?? {}))) {
+        if (String(text) === text)
+            headers[name] = text;
+    }
+    return { status: Number(answer.status), headers, body: answer.body };
+};
 /**
  * The service's way to the forge: OpenChamber's callback listener
  * (`OPENCHAMBER_HOST_CALLBACK_URL`), which checks the handle, keeps the request
@@ -250,41 +293,272 @@ export const createSourceControlForge = ({ env }) => {
         throw new Error(`${OPENCHAMBER_HOST_CALLBACK_URL} is not set: only a service that provides "source-control" can reach a forge.`);
     const url = `${base.replace(/\/+$/, '')}${SOURCE_CONTROL_OUTBOUND_PATH}`;
     return {
-        async request(handle, request) {
-            let response;
-            try {
-                response = await fetch(url, {
-                    method: 'POST',
-                    headers: { authorization: `Bearer ${handle}`, 'content-type': 'application/json' },
-                    body: JSON.stringify(request),
-                    // A little past OpenChamber's own deadline, so its answer wins.
-                    signal: AbortSignal.timeout(SOURCE_CONTROL_OUTBOUND_TIMEOUT_MS + 5_000),
-                });
-            }
-            catch (error) {
-                throw new SourceControlForgeError(`OpenChamber did not answer: ${error instanceof Error ? error.message : String(error)}`, 'HOST_UNAVAILABLE', 0);
-            }
-            let answer;
-            try {
-                answer = Object(await response.json());
-            }
-            catch {
-                throw new SourceControlForgeError('OpenChamber answered with something other than JSON', 'HOST_UNAVAILABLE', response.status);
-            }
-            if (!response.ok) {
-                const message = answer.error?.message;
-                const code = answer.error?.code;
-                throw new SourceControlForgeError(String(message) === message && message.length > 0 ? message : `OpenChamber refused the request (${response.status})`, String(code) === code && code.length > 0 ? code : 'OUTBOUND_REFUSED', response.status);
-            }
-            if (!Number.isSafeInteger(answer.status) || String(answer.body) !== answer.body) {
-                throw new SourceControlForgeError('OpenChamber relayed a malformed forge answer', 'HOST_UNAVAILABLE', response.status);
-            }
-            const headers = {};
-            for (const [name, text] of Object.entries(Object(answer.headers ?? {}))) {
-                if (String(text) === text)
-                    headers[name] = text;
-            }
-            return { status: Number(answer.status), headers, body: answer.body };
-        },
+        request: (handle, request) => postOutbound(url, handle, request, SOURCE_CONTROL_OUTBOUND_TIMEOUT_MS, (message, code, status) => new SourceControlForgeError(message, code, status)),
+    };
+};
+/*
+ * Notifications: a service with `provides: ["notifications"]` is the delivery
+ * channel `contributes.notifications` describes, next to the desktop and the
+ * phone. OpenChamber keeps the account and its token. Once the user connects
+ * one, every notification OpenChamber decides to show goes to the service at
+ * `NOTIFICATIONS_PROVIDER_PATH` as `notify`, and the service sends it on
+ * through OpenChamber's outbound proxy (`createNotificationsOutbound`), which
+ * pins the account's origin and adds the token. The service never sees a token.
+ */
+/** Route on the service loopback OpenChamber posts every notifications call to. */
+export const NOTIFICATIONS_PROVIDER_PATH = '/notifications';
+/** The `v` of every request; a service answers a version it does not know with HTTP 400. */
+export const NOTIFICATIONS_PROVIDER_WIRE_VERSION = 1;
+/**
+ * `auth.verify` reads who a candidate token belongs to, `auth.probe` whether
+ * an instance is this channel's server, `notify` delivers one notification.
+ */
+export const NOTIFICATIONS_PROVIDER_METHODS = ['auth.verify', 'auth.probe', 'notify'];
+/** A notification is delivered within this deadline; a slower service drops it. */
+export const NOTIFICATIONS_PROVIDER_NOTIFY_TIMEOUT_MS = 10_000;
+export const NOTIFICATIONS_PROVIDER_AUTH_TIMEOUT_MS = 15_000;
+/** Bytes of an answer OpenChamber reads. */
+export const NOTIFICATIONS_PROVIDER_RESPONSE_MAX = 16_000;
+/** Characters of `error.message` OpenChamber reads. */
+export const NOTIFICATIONS_PROVIDER_ERROR_MESSAGE_MAX = 2_000;
+/** No call for this long stops the service; the next call starts it again. */
+export const NOTIFICATIONS_PROVIDER_IDLE_MS = 10 * 60_000;
+/** Route on the callback listener a service sends the channel's requests to. */
+export const NOTIFICATIONS_OUTBOUND_PATH = '/notifications/outbound';
+/** One outbound request may take this long; the call's own deadline may end it sooner. */
+export const NOTIFICATIONS_OUTBOUND_TIMEOUT_MS = 20_000;
+export const notificationsProviderTimeoutMs = (method) => (method === 'notify' ? NOTIFICATIONS_PROVIDER_NOTIFY_TIMEOUT_MS : NOTIFICATIONS_PROVIDER_AUTH_TIMEOUT_MS);
+/**
+ * The kinds OpenChamber notifies about. `ready`: the agent finished; `error`:
+ * the turn failed; `question` and `permission`: the agent waits for the user;
+ * `review`: an auto-review ended; the `goal_*` kinds: a session goal settled.
+ * Which kinds reach a channel follows the user's own notification toggles.
+ */
+export const GUEST_NOTIFICATION_KINDS = ['ready', 'error', 'question', 'permission', 'review', 'goal_complete', 'goal_blocked', 'goal_budget'];
+export const isNotificationsProviderMethod = (value) => (NOTIFICATIONS_PROVIDER_METHODS.some((method) => method === value));
+/** `undefined` is an account that is neither `null` nor `{ id, login }`. */
+const readNotificationsAccount = (account) => {
+    if (account === null)
+        return null;
+    if (Object(account) !== account || account === undefined)
+        return undefined;
+    const { id, login } = account;
+    if (String(id) !== id || id.length === 0)
+        return undefined;
+    if (login !== null && (String(login) !== login || login.length === 0))
+        return undefined;
+    return { id, login };
+};
+/**
+ * A service's read of the body OpenChamber posted to
+ * `NOTIFICATIONS_PROVIDER_PATH`. OpenChamber built `input`, so this checks the
+ * envelope, not every field, and the service bundle needs no schema library.
+ * `null` is a body that is not a notifications call of this wire version;
+ * answer it with HTTP 400.
+ */
+export const readNotificationsProviderRequest = (body) => {
+    let wire;
+    try {
+        const parsed = JSON.parse(body);
+        if (Object(parsed) !== parsed || parsed === null)
+            return null;
+        wire = parsed;
+    }
+    catch {
+        return null;
+    }
+    const { v, requestId, method, provider, session, input } = wire;
+    if (v !== NOTIFICATIONS_PROVIDER_WIRE_VERSION)
+        return null;
+    if (String(requestId) !== requestId || requestId.length === 0)
+        return null;
+    if (String(provider) !== provider || provider.length === 0)
+        return null;
+    if (String(method) !== method || !isNotificationsProviderMethod(method))
+        return null;
+    if (Object(input) !== input || Array.isArray(input))
+        return null;
+    if (Object(session) !== session || session === null || session === undefined)
+        return null;
+    const { instance, handle } = session;
+    if (String(instance) !== instance || instance.length === 0 || String(handle) !== handle || handle.length === 0)
+        return null;
+    const account = readNotificationsAccount(session.account);
+    if (account === undefined)
+        return null;
+    // SAFETY: `input` is a plain object parsed from JSON, so every value in it is JSON.
+    return { v: NOTIFICATIONS_PROVIDER_WIRE_VERSION, requestId, method, provider, session: { instance, handle, account }, input: input };
+};
+/**
+ * OpenChamber refused the request (an expired handle, a path off the
+ * instance, a body too large), could not reach the channel's server, or did
+ * not answer. `status` is the callback listener's HTTP status, `0` when it
+ * gave none; `code` is its error code (`HOST_UNAVAILABLE` when there was no
+ * usable answer).
+ */
+export class NotificationsOutboundError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = 'NotificationsOutboundError';
+        this.code = code;
+        this.status = status;
+    }
+}
+/**
+ * The service's way to the channel's server: OpenChamber's callback listener
+ * (`OPENCHAMBER_HOST_CALLBACK_URL`), which checks the handle, keeps the
+ * request on the account's origin and adds the token. Plain `fetch`, no
+ * dependencies. Throws `NotificationsOutboundError` when OpenChamber refuses
+ * the request; an answer of any status from the server resolves.
+ */
+export const createNotificationsOutbound = ({ env }) => {
+    const base = env[OPENCHAMBER_HOST_CALLBACK_URL];
+    if (!base)
+        throw new Error(`${OPENCHAMBER_HOST_CALLBACK_URL} is not set: only a service that provides "notifications" can reach a channel's server.`);
+    const url = `${base.replace(/\/+$/, '')}${NOTIFICATIONS_OUTBOUND_PATH}`;
+    return {
+        request: (handle, request) => postOutbound(url, handle, request, NOTIFICATIONS_OUTBOUND_TIMEOUT_MS, (message, code, status) => new NotificationsOutboundError(message, code, status)),
+    };
+};
+/*
+ * Tracker: a service with `provides: ["tracker"]` is the work item tracker
+ * `contributes.tracker` describes, next to Linear. OpenChamber keeps the
+ * accounts and their tokens (pasted or minted through OAuth), the project
+ * mapping, the session comment preference and the session records; it
+ * forwards the reads and the two writes to the service at
+ * `TRACKER_PROVIDER_PATH`. The service never sees a token: it reaches the
+ * tracker's server through OpenChamber's outbound proxy
+ * (`createTrackerOutbound`), which pins the instance origin and adds the
+ * account's credential itself. Every item answered goes to the UI in the
+ * neutral tracker shapes, so the picker, the composer, New Worktree, linked
+ * items and tracked items draw it as they draw a Linear issue.
+ */
+/** Route on the service loopback OpenChamber posts every tracker call to. */
+export const TRACKER_PROVIDER_PATH = '/tracker';
+/** The `v` of every request; a service answers a version it does not know with HTTP 400. */
+export const TRACKER_PROVIDER_WIRE_VERSION = 1;
+/**
+ * Every call OpenChamber forwards. `auth.probe` asks whether an instance is
+ * this tracker's server, `auth.verify` who a credential belongs to (the handle
+ * carries a pasted token or an OAuth access token); the reads answer in the
+ * neutral shapes; `items.updateState` and `comments.create` are the two
+ * writes, the only calls whose handle may send anything but `GET`.
+ */
+export const TRACKER_PROVIDER_METHODS = [
+    'auth.probe',
+    'auth.verify',
+    'items.list',
+    'items.get',
+    'items.updateState',
+    'items.liveSummaries',
+    'states.list',
+    'containers.list',
+    'comments.create',
+];
+/** The calls that change something on the tracker. */
+export const TRACKER_PROVIDER_WRITE_METHODS = ['items.updateState', 'comments.create'];
+export const TRACKER_PROVIDER_AUTH_TIMEOUT_MS = 15_000;
+export const TRACKER_PROVIDER_READ_TIMEOUT_MS = 20_000;
+export const TRACKER_PROVIDER_WRITE_TIMEOUT_MS = 30_000;
+/** Bytes of an answer OpenChamber reads: a page of items with their labels and people. */
+export const TRACKER_PROVIDER_RESPONSE_MAX = 2_000_000;
+/** Characters of `error.message` OpenChamber reads. */
+export const TRACKER_PROVIDER_ERROR_MESSAGE_MAX = 2_000;
+/** No call for this long stops the service; the next call starts it again. */
+export const TRACKER_PROVIDER_IDLE_MS = 10 * 60_000;
+/** Items in one `items.list` page, children or comments of one item, states of one container. */
+export const TRACKER_PROVIDER_LIST_MAX = 100;
+/** Identifiers in one `items.liveSummaries` call. */
+export const TRACKER_PROVIDER_LIVE_SUMMARIES_MAX = 50;
+/** Containers in one `containers.list` answer. */
+export const TRACKER_PROVIDER_CONTAINERS_MAX = 500;
+/** Route on the callback listener a service sends the tracker's requests to. */
+export const TRACKER_OUTBOUND_PATH = '/tracker/outbound';
+/** One outbound request may take this long; the call's own deadline may end it sooner. */
+export const TRACKER_OUTBOUND_TIMEOUT_MS = 20_000;
+export const isTrackerProviderWriteMethod = (method) => (TRACKER_PROVIDER_WRITE_METHODS.some((write) => write === method));
+/** How long OpenChamber waits for the service to answer `method`. */
+export const trackerProviderTimeoutMs = (method) => {
+    if (method === 'auth.probe' || method === 'auth.verify')
+        return TRACKER_PROVIDER_AUTH_TIMEOUT_MS;
+    if (isTrackerProviderWriteMethod(method))
+        return TRACKER_PROVIDER_WRITE_TIMEOUT_MS;
+    return TRACKER_PROVIDER_READ_TIMEOUT_MS;
+};
+export const isTrackerProviderMethod = (value) => (TRACKER_PROVIDER_METHODS.some((method) => method === value));
+/**
+ * A service's read of the body OpenChamber posted to `TRACKER_PROVIDER_PATH`.
+ * OpenChamber built `input`, so this checks the envelope, not every field, and
+ * the service bundle needs no schema library. `null` is a body that is not a
+ * tracker call of this wire version; answer it with HTTP 400.
+ */
+export const readTrackerProviderRequest = (body) => {
+    let wire;
+    try {
+        const parsed = JSON.parse(body);
+        if (Object(parsed) !== parsed || parsed === null)
+            return null;
+        wire = parsed;
+    }
+    catch {
+        return null;
+    }
+    const { v, requestId, method, provider, session, input } = wire;
+    if (v !== TRACKER_PROVIDER_WIRE_VERSION)
+        return null;
+    if (String(requestId) !== requestId || requestId.length === 0)
+        return null;
+    if (String(provider) !== provider || provider.length === 0)
+        return null;
+    if (String(method) !== method || !isTrackerProviderMethod(method))
+        return null;
+    if (Object(input) !== input || Array.isArray(input))
+        return null;
+    if (Object(session) !== session || session === null || session === undefined)
+        return null;
+    const { instance, handle } = session;
+    if (String(instance) !== instance || instance.length === 0 || String(handle) !== handle || handle.length === 0)
+        return null;
+    // The account shape is the notification channel's: `{ id, login | null }` or null.
+    const account = readNotificationsAccount(session.account);
+    if (account === undefined)
+        return null;
+    // SAFETY: `input` is a plain object parsed from JSON, so every value in it is JSON.
+    return { v: TRACKER_PROVIDER_WIRE_VERSION, requestId, method, provider, session: { instance, handle, account }, input: input };
+};
+/**
+ * OpenChamber refused the request (an expired handle, a path off the
+ * instance, a body too large, a write through a read's handle), could not
+ * reach the tracker's server, or did not answer. `status` is the callback
+ * listener's HTTP status, `0` when it gave none; `code` is its error code
+ * (`HOST_UNAVAILABLE` when there was no usable answer).
+ */
+export class TrackerOutboundError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = 'TrackerOutboundError';
+        this.code = code;
+        this.status = status;
+    }
+}
+/**
+ * The service's way to the tracker's server: OpenChamber's callback listener
+ * (`OPENCHAMBER_HOST_CALLBACK_URL`), which checks the handle, keeps the
+ * request on the account's origin and adds the credential. Plain `fetch`, no
+ * dependencies. Throws `TrackerOutboundError` when OpenChamber refuses the
+ * request; an answer of any status from the server resolves. A read's handle
+ * sends `GET` only; `items.updateState` and `comments.create` may send writes.
+ */
+export const createTrackerOutbound = ({ env }) => {
+    const base = env[OPENCHAMBER_HOST_CALLBACK_URL];
+    if (!base)
+        throw new Error(`${OPENCHAMBER_HOST_CALLBACK_URL} is not set: only a service that provides "tracker" can reach a tracker's server.`);
+    const url = `${base.replace(/\/+$/, '')}${TRACKER_OUTBOUND_PATH}`;
+    return {
+        request: (handle, request) => postOutbound(url, handle, request, TRACKER_OUTBOUND_TIMEOUT_MS, (message, code, status) => new TrackerOutboundError(message, code, status)),
     };
 };

package/dist/service-surface-schemas.d.ts

@@ -36,6 +36,7 @@ export declare const surfaceInputEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     }>;
     key: z.ZodString;
     code: z.ZodString;
+    keyCode: z.ZodOptional<z.ZodNumber>;
     modifiers: z.ZodObject<{
         alt: z.ZodBoolean;
         ctrl: z.ZodBoolean;
@@ -89,6 +90,7 @@ export declare const surfaceViewerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodO
         }>;
         key: z.ZodString;
         code: z.ZodString;
+        keyCode: z.ZodOptional<z.ZodNumber>;
         modifiers: z.ZodObject<{
             alt: z.ZodBoolean;
             ctrl: z.ZodBoolean;

package/dist/service-surface-schemas.js

@@ -18,6 +18,7 @@ export const surfaceInputEventSchema = z.discriminatedUnion('type', [
         action: z.enum(['down', 'up']),
         key: z.string().min(1).max(64),
         code: z.string().max(64),
+        keyCode: z.number().int().min(0).max(255).optional(),
         modifiers: modifiersSchema,
     }),
     z.object({ type: z.literal('text'), text: z.string().min(1).max(SURFACE_TEXT_MAX) }),

package/dist/service-surface.d.ts

@@ -93,6 +93,11 @@ export type SurfaceKeyEvent = {
     key: string;
     /** `KeyboardEvent.code`. */
     code: string;
+    /**
+     * `KeyboardEvent.keyCode` as the viewer's browser computed it for the user's
+     * keyboard layout, 0 to 255. Older hosts omit it.
+     */
+    keyCode?: number;
     modifiers: SurfaceModifiers;
 };
 /** Text the user pasted or composed; type it as is. */

package/dist/service-surface.js

@@ -99,7 +99,11 @@ const readEvent = (value) => {
             return null;
         if (!isText(value.key) || !isText(value.code) || value.key.length > 64 || value.code.length > 64)
             return null;
-        return { type: 'key', action: value.action, key: value.key, code: value.code, modifiers };
+        if (value.keyCode === undefined)
+            return { type: 'key', action: value.action, key: value.key, code: value.code, modifiers };
+        if (!isFiniteNumber(value.keyCode) || !Number.isInteger(value.keyCode) || value.keyCode < 0 || value.keyCode > 255)
+            return null;
+        return { type: 'key', action: value.action, key: value.key, code: value.code, keyCode: value.keyCode, modifiers };
     }
     return null;
 };

package/dist/session-events.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Session events for an extension's service (`contributes.sessionEvents`).
+ *
+ * OpenChamber posts each event a package subscribed to as one HTTP request to
+ * the service at `SESSION_EVENTS_PATH`, from every project, whether or not a
+ * window is open. Approving the package is the subscription: the request
+ * carries identifiers only (`event`), and the `transcript` capability, asked
+ * for with `content: true`, adds what the agent said or asked (`content`).
+ * The service answers `{ ok: true }` once it has taken the event; OpenChamber
+ * reads nothing else from the answer. Which projects an extension acts on is
+ * its own business: filter on `event.project.directory`.
+ */
+/**
+ * `turn-finished`: the session went idle with nothing waiting (no running
+ * subagent, no open permission, question or page, no goal or auto-review
+ * step still driving it). `turn-failed`: the turn ended in an error.
+ * `permission-asked`: the agent asked for a permission the user has to
+ * answer. `question-asked`: the agent asked the user a question through a
+ * form or a page. A turn the user stopped emits nothing.
+ */
+export declare const GUEST_SESSION_EVENT_TYPES: readonly ['turn-finished', 'turn-failed', 'permission-asked', 'question-asked'];
+export type GuestSessionEventType = (typeof GUEST_SESSION_EVENT_TYPES)[number];
+/** Route on the service loopback OpenChamber posts every event to. */
+export declare const SESSION_EVENTS_PATH = "/session-events";
+/** The `v` of every request; a service answers a version it does not know with HTTP 400. */
+export declare const SESSION_EVENTS_WIRE_VERSION = 1;
+/** One delivery may take this long; a slower service drops that event. */
+export declare const SESSION_EVENT_TIMEOUT_MS = 10000;
+/** No event for this long stops the service; the next event starts it again. */
+export declare const SESSION_EVENTS_IDLE_MS: number;
+/** Characters of the agent's reply carried in `content`; a longer reply is cut and flagged. */
+export declare const SESSION_EVENT_REPLY_MAX = 64000;
+/** Events kept while the service starts; newer ones past this are dropped. */
+export declare const SESSION_EVENT_PENDING_MAX = 200;
+/** Characters of `error` OpenChamber reads from a failed answer. */
+export declare const SESSION_EVENT_ERROR_MAX = 2000;
+/**
+ * `contributes.sessionEvents`: which events the service wants, and whether it
+ * also wants their content. Needs `contributes.service`; the service needs no
+ * panel or background entry for this alone.
+ */
+export type SessionEventsContribution = {
+    /** 1 to 4 distinct types. */
+    events: GuestSessionEventType[];
+    /** Asks for the `transcript` capability: the reply, the question, the permission's detail. */
+    content?: true;
+};
+/** What the catalog and the approval dialog show of the subscription. */
+export type PublicSessionEvents = {
+    events: GuestSessionEventType[];
+    content: boolean;
+};
+/**
+ * An item the user linked to the session (a tracker issue, a pull request,
+ * an external link), as the session stores it: identifiers and the link,
+ * never the item's title. `id` is the stored entry id (`owner/repo#12`,
+ * `linear:OPE-367`, `link:<url>`); `kind` is the link's kind as stored
+ * (`issue`, `pull`, `external`, or a tracker's own kind); `provider` names the
+ * tracker when one owns the item and `identifier` is its key there (`OPE-367`).
+ */
+export type GuestSessionLinkedItem = {
+    id: string;
+    kind: string;
+    url: string;
+    provider?: string;
+    identifier?: string;
+    /** The change request or issue number on a Git host. */
+    number?: number;
+};
+/** The agent's final answer of the turn, cut at `SESSION_EVENT_REPLY_MAX` when `replyTruncated`. */
+export type GuestTurnFinishedContent = {
+    type: 'turn-finished';
+    sessionTitle: string | null;
+    reply: string;
+    replyTruncated: boolean;
+};
+export type GuestTurnFailedContent = {
+    type: 'turn-failed';
+    sessionTitle: string | null;
+    error: {
+        type: string;
+        message: string;
+    };
+};
+/** What the agent wants to do: the permission's action, the resources it names, and its note. */
+export type GuestPermissionAskedContent = {
+    type: 'permission-asked';
+    sessionTitle: string | null;
+    action: string;
+    resources: string[];
+    message: string | null;
+};
+export type GuestQuestionAskedContent = {
+    type: 'question-asked';
+    sessionTitle: string | null;
+    ask: {
+        kind: 'form';
+        id: string;
+        title: string;
+        fields: Array<{
+            title: string;
+            description: string | null;
+        }>;
+    } | {
+        kind: 'page';
+        id: string;
+        title: string;
+    };
+};
+export type GuestSessionEventContent = GuestTurnFinishedContent | GuestTurnFailedContent | GuestPermissionAskedContent | GuestQuestionAskedContent;
+/**
+ * One event, as OpenChamber posts it. `event` is what every subscriber gets;
+ * `content` comes only with the `transcript` grant, and only on the types
+ * that have content. `project.directory` is the session's directory, `null`
+ * when OpenChamber does not know it. `session.parentId` is set for a
+ * subagent's session. `permission.requestId` names the request on a
+ * `permission-asked` event.
+ */
+export type GuestSessionEventRequest = {
+    v: typeof SESSION_EVENTS_WIRE_VERSION;
+    requestId: string;
+    event: {
+        /** OpenCode's event id, or one OpenChamber made for an event it synthesized. */
+        id: string;
+        type: GuestSessionEventType;
+        /** Epoch milliseconds. */
+        at: number;
+        session: {
+            id: string;
+            parentId: string | null;
+        };
+        project: {
+            directory: string | null;
+        };
+        linked: GuestSessionLinkedItem[];
+        permission?: {
+            requestId: string;
+        };
+    };
+    content?: GuestSessionEventContent;
+};
+/**
+ * What the service answers. `ok: false` with an `error` is a delivery that
+ * failed; OpenChamber logs the text and nothing else, so say what went wrong
+ * on the service's side, never what the event contained.
+ */
+export type GuestSessionEventResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const isGuestSessionEventType: (value: string) => value is GuestSessionEventType;
+/**
+ * A service's read of the body OpenChamber posted to `SESSION_EVENTS_PATH`.
+ * OpenChamber built the event, so this checks the envelope and the fields a
+ * service branches on, not every content field, and the service bundle needs
+ * no schema library. `null` is a body that is not a session event of this
+ * wire version; answer it with HTTP 400.
+ */
+export declare const readSessionEventRequest: (body: string) => GuestSessionEventRequest | null;