@vibesdotdev/session 1.0.0-rc.1 → 1.0.0-rc.3

package/dist/admission/admit-caller.context.descriptor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Caller admission context descriptor (`session/admit-caller`).
+ */
+declare const _default: {
+    id: string;
+    kind: "context";
+    name?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    hardware?: string[] | undefined;
+    enabled?: boolean | undefined;
+    priority?: number | undefined;
+    capabilityId?: string | undefined;
+    requiredContext?: string[] | undefined;
+    optionalContext?: string[] | undefined;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+    valueKind?: "data" | "service" | undefined;
+    valueSchema?: unknown;
+    config?: {
+        sources: ("literal" | "workspace" | "floor")[];
+        subset?: true | undefined;
+    } | undefined;
+};
+export default _default;
+//# sourceMappingURL=admit-caller.context.descriptor.d.ts.map

package/dist/admission/admit-caller.context.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit-caller.context.descriptor.d.ts","sourceRoot":"","sources":["../../src/admission/admit-caller.context.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKH,wBAGG"}

package/dist/admission/admit-caller.context.descriptor.js

@@ -0,0 +1,10 @@
+/**
+ * Caller admission context descriptor (`session/admit-caller`).
+ */
+import { createContextDescriptor } from '@vibesdotdev/kernel/factory/context';
+import { ADMIT_CALLER_CONTEXT_ID } from '@vibesdotdev/kernel/schemas/invoke-caller';
+export default createContextDescriptor({
+    id: ADMIT_CALLER_CONTEXT_ID,
+    description: 'Admit a tool call\'s caller: its running instance (and, for writes, its session) before the call runs.'
+});
+//# sourceMappingURL=admit-caller.context.descriptor.js.map

package/dist/admission/admit-caller.context.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit-caller.context.descriptor.js","sourceRoot":"","sources":["../../src/admission/admit-caller.context.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AAEpF,eAAe,uBAAuB,CAAC;IACtC,EAAE,EAAE,uBAAuB;IAC3B,WAAW,EAAE,wGAAwG;CACrH,CAAC,CAAC"}

package/dist/admission/admit-caller.context.impl.d.ts

@@ -0,0 +1,8 @@
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+import type { AdmitCaller } from '@vibesdotdev/kernel/schemas/invoke-caller';
+/** The admission function; the manager it uses belongs to the session runtime client. */
+declare const defaultExport: {
+    provide: (runtime: VibesRuntime) => Promise<AdmitCaller>;
+};
+export default defaultExport;
+//# sourceMappingURL=admit-caller.context.impl.d.ts.map

package/dist/admission/admit-caller.context.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit-caller.context.impl.d.ts","sourceRoot":"","sources":["../../src/admission/admit-caller.context.impl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAC;AAI7E,yFAAyF;AACzF,QAAA,MAAM,aAAa;uBACO,YAAY,KAAG,OAAO,CAAC,WAAW,CAAC;CAS5D,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/admission/admit-caller.context.impl.js

@@ -0,0 +1,15 @@
+import {} from '@vibesdotdev/kernel';
+import { getVibesClient } from '@vibesdotdev/kernel/client';
+import { assertSessionRuntime } from "../client.js";
+import { admitCaller, ToolSafetyFieldsSchema } from "./admit-caller.js";
+/** The admission function; the manager it uses belongs to the session runtime client. */
+const defaultExport = {
+    provide: async (runtime) => {
+        assertSessionRuntime(runtime);
+        const client = await getVibesClient('session', runtime);
+        const describeTool = (toolId) => ToolSafetyFieldsSchema.parse((runtime.hasKind('tools/tool') ? runtime.assets('tools/tool').descriptor(toolId) : undefined) ?? {});
+        return async (request) => admitCaller(await client.getManager(), request, describeTool);
+    }
+};
+export default defaultExport;
+//# sourceMappingURL=admit-caller.context.impl.js.map

package/dist/admission/admit-caller.context.impl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit-caller.context.impl.js","sourceRoot":"","sources":["../../src/admission/admit-caller.context.impl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,oBAAoB,EAAsB,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAyB,MAAM,mBAAmB,CAAC;AAE/F,yFAAyF;AACzF,MAAM,aAAa,GAAG;IACrB,OAAO,EAAE,KAAK,EAAE,OAAqB,EAAwB,EAAE;QAC9D,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,cAAc,CAAgB,SAAS,EAAE,OAAO,CAAC,CAAC;QACvE,MAAM,YAAY,GAAG,CAAC,MAAc,EAAoB,EAAE,CACzD,sBAAsB,CAAC,KAAK,CAC3B,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CACnG,CAAC;QACH,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,MAAM,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IACzF,CAAC;CACD,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/admission/admit-caller.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Caller admission: the one step every tool call takes before its invocation
+ * identity is fixed (`invokeTool`, tools/src/execution/invoke.ts). It gives the
+ * caller its running instance — one live row in the instance registry
+ * (`session.connections`) — whichever surface the call came through. How the
+ * caller arrived (MCP connection, daemon socket, in-process host) is read from
+ * the request as data and recorded on the instance; it never selects a path.
+ */
+import * as z from 'zod/v4';
+import { type AdmitCallerRequest, type AdmittedCall } from '@vibesdotdev/kernel/schemas/invoke-caller';
+import type { SessionManager } from '../manager/index.ts';
+import type { RegisterInstanceInput } from '../schemas/index.ts';
+/**
+ * The instance a call belongs to.
+ * - A declared `instanceId` is the instance.
+ * - An MCP connection is one instance per connection; its live transport touches it.
+ * - A harness conversation is one instance, keyed on (who, which conversation),
+ *   across every host its calls run in; anything else is keyed on (this host,
+ *   who). So two seats of one agent stay two instances. An in-process host
+ *   keeps its seat open, so it hosts (heartbeats) the instance until it closes.
+ */
+export declare function instanceFor(request: AdmitCallerRequest, hostKey: string): Omit<RegisterInstanceInput, 'clientName'> | undefined;
+/** The tool fields that decide whether a call writes: its declared safety category, per action when declared. */
+export declare const ToolSafetyFieldsSchema: z.ZodObject<{
+    safety: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodObject<{
+        category: z.ZodString;
+    }, z.core.$strip>, z.ZodTransform<string, {
+        category: string;
+    }>>]>>>;
+    schemas: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        actionSafety: z.ZodCatch<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ToolSafetyFields = z.infer<typeof ToolSafetyFieldsSchema>;
+/** The call input fields admission reads: the selected action and a named target session. */
+declare const CallInputSchema: z.ZodObject<{
+    action: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    sessionId: z.ZodCatch<z.ZodOptional<z.ZodUUID>>;
+}, z.core.$strip>;
+/**
+ * Whether the call writes, by the platform's one rule (the same one host
+ * approval uses, external/src/harness/live-tools.ts): the selected action's
+ * declared safety, else the tool's; only a declared `read` is a read.
+ */
+export declare function callWrites(fields: ToolSafetyFields, input: z.infer<typeof CallInputSchema>): boolean;
+/**
+ * Admit one call. Its instance is registered and kept alive. Its session is,
+ * in order: the session the caller already carries; the session the call names
+ * (`input.sessionId`, e.g. a message into a room); the session its instance is
+ * working in. A call that writes and still has no session gets one, owned by
+ * its participant. Membership follows authorization: only once the call
+ * succeeds does the instance take the lease and work in that session; a
+ * failed write archives the session it minted.
+ */
+export declare function admitCaller(manager: SessionManager, request: AdmitCallerRequest, describeTool: (toolId: string) => ToolSafetyFields): Promise<AdmittedCall>;
+export {};
+//# sourceMappingURL=admit-caller.d.ts.map

package/dist/admission/admit-caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit-caller.d.ts","sourceRoot":"","sources":["../../src/admission/admit-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,YAAY,EAEjB,MAAM,2CAA2C,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAoBjE;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAC1B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,MAAM,GACb,IAAI,CAAC,qBAAqB,EAAE,YAAY,CAAC,GAAG,SAAS,CA0BvD;AAED,iHAAiH;AACjH,eAAO,MAAM,sBAAsB;;;;;;;;;iBAMjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,6FAA6F;AAC7F,QAAA,MAAM,eAAe;;;iBAGnB,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,GAAG,OAAO,CAMpG;AAeD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAChC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,GAChD,OAAO,CAAC,YAAY,CAAC,CA8CvB"}

package/dist/admission/admit-caller.js

@@ -0,0 +1,163 @@
+/**
+ * Caller admission: the one step every tool call takes before its invocation
+ * identity is fixed (`invokeTool`, tools/src/execution/invoke.ts). It gives the
+ * caller its running instance — one live row in the instance registry
+ * (`session.connections`) — whichever surface the call came through. How the
+ * caller arrived (MCP connection, daemon socket, in-process host) is read from
+ * the request as data and recorded on the instance; it never selects a path.
+ */
+import * as z from 'zod/v4';
+import { sha256Hex } from '@vibesdotdev/shared/hashing';
+import { RuntimeInvokeCallerSchema } from '@vibesdotdev/kernel/schemas/invoke-caller';
+/** A metadata key that is absent, empty or not text carries nothing. */
+const MetadataTextSchema = z.string().trim().min(1).optional().catch(undefined);
+/** The call metadata admission reads: how the caller arrived. */
+const AdmissionMetadataSchema = z.object({
+    'mcp.transportSessionId': MetadataTextSchema,
+    'mcp.connectionKey': MetadataTextSchema,
+    'mcp.transportMode': MetadataTextSchema,
+    'invoke.transport': MetadataTextSchema
+});
+/** A caller with no identity (an internal runtime call) is no one, and has no instance. */
+function hasIdentity(caller, transportKey) {
+    return Boolean(transportKey || caller?.instanceId || caller?.participantId || caller?.agentId || caller?.harness);
+}
+/**
+ * The instance a call belongs to.
+ * - A declared `instanceId` is the instance.
+ * - An MCP connection is one instance per connection; its live transport touches it.
+ * - A harness conversation is one instance, keyed on (who, which conversation),
+ *   across every host its calls run in; anything else is keyed on (this host,
+ *   who). So two seats of one agent stay two instances. An in-process host
+ *   keeps its seat open, so it hosts (heartbeats) the instance until it closes.
+ */
+export function instanceFor(request, hostKey) {
+    const metadata = AdmissionMetadataSchema.parse(request.metadata ?? {});
+    const caller = request.caller;
+    const mcpKey = metadata['mcp.transportSessionId'] ?? metadata['mcp.connectionKey'];
+    if (!hasIdentity(caller, mcpKey))
+        return undefined;
+    const mcpTransport = mcpKey ? `mcp-${metadata['mcp.transportMode'] ?? 'stdio'}` : undefined;
+    const transport = metadata['invoke.transport'] ?? mcpTransport ?? 'in-process';
+    const who = {
+        participantId: caller?.participantId,
+        agentId: caller?.agentId,
+        harness: caller?.harness,
+        harnessSessionId: caller?.harnessSessionId
+    };
+    if (caller?.instanceId)
+        return { instanceId: caller.instanceId, transport, ...who };
+    if (mcpKey)
+        return { instanceId: mcpKey, transport, ...who };
+    // One harness conversation is one instance whichever host its calls run in
+    // (each one-shot `vibes` run is its own host); without one, the host is the seat.
+    const seat = who.harnessSessionId
+        ? ['harness', who.participantId ?? who.agentId ?? who.harness, who.harnessSessionId].join('|')
+        : [hostKey, who.participantId ?? who.agentId ?? who.harness].join('|');
+    return {
+        instanceId: `${transport}:${sha256Hex(seat).slice(0, 24)}`,
+        transport,
+        hosted: transport === 'in-process',
+        ...who
+    };
+}
+/** The tool fields that decide whether a call writes: its declared safety category, per action when declared. */
+export const ToolSafetyFieldsSchema = z.object({
+    safety: z
+        .union([z.string(), z.object({ category: z.string() }).transform((safety) => safety.category)])
+        .optional()
+        .catch(undefined),
+    schemas: z.object({ actionSafety: z.record(z.string(), z.string()).optional().catch(undefined) }).optional().catch(undefined)
+});
+/** The call input fields admission reads: the selected action and a named target session. */
+const CallInputSchema = z.object({
+    action: z.string().min(1).optional().catch(undefined),
+    sessionId: z.uuid().optional().catch(undefined)
+});
+/**
+ * Whether the call writes, by the platform's one rule (the same one host
+ * approval uses, external/src/harness/live-tools.ts): the selected action's
+ * declared safety, else the tool's; only a declared `read` is a read.
+ */
+export function callWrites(fields, input) {
+    const actionSafety = fields.schemas?.actionSafety;
+    const selected = input.action ? actionSafety?.[input.action] : undefined;
+    if (selected !== undefined)
+        return selected !== 'read';
+    if (!input.action && actionSafety && Object.values(actionSafety).some((safety) => safety !== 'read'))
+        return true;
+    return fields.safety !== 'read';
+}
+/** The tool whose own lifecycle binds and creates sessions; admission never mints for it. */
+const SESSION_LIFECYCLE_TOOL = 'session';
+/** The participant a caller acts as: declared, else its harness seat, else its agent identity. */
+async function participantFor(manager, caller) {
+    if (caller?.participantId)
+        return caller.participantId;
+    if (caller?.agentId && caller.harnessSessionId) {
+        return (await manager.ensureHarnessSeat({ agentId: caller.agentId, harnessSessionId: caller.harnessSessionId })).participantId;
+    }
+    if (caller?.agentId)
+        return manager.identifyParticipant(caller.agentId);
+    return undefined;
+}
+/**
+ * Admit one call. Its instance is registered and kept alive. Its session is,
+ * in order: the session the caller already carries; the session the call names
+ * (`input.sessionId`, e.g. a message into a room); the session its instance is
+ * working in. A call that writes and still has no session gets one, owned by
+ * its participant. Membership follows authorization: only once the call
+ * succeeds does the instance take the lease and work in that session; a
+ * failed write archives the session it minted.
+ */
+export async function admitCaller(manager, request, describeTool) {
+    const instance = instanceFor(request, manager.hostKey);
+    if (!instance)
+        return { caller: request.caller };
+    const registered = await manager.ensureInstance({
+        ...instance,
+        clientName: instance.harness ?? instance.agentId ?? instance.transport
+    });
+    const input = CallInputSchema.parse(request.input ?? {});
+    // A session the call only names (a message into a room) makes the caller a
+    // member there; it does not become the session the instance works in.
+    const named = !request.caller?.sessionId && input.sessionId !== undefined;
+    let sessionId = request.caller?.sessionId ?? input.sessionId ?? (await manager.instanceSession(instance.instanceId));
+    let participantId = request.caller?.participantId;
+    let minted;
+    if (!sessionId && request.toolId !== SESSION_LIFECYCLE_TOOL && callWrites(describeTool(request.toolId), input)) {
+        participantId ??= await participantFor(manager, request.caller);
+        if (participantId) {
+            const created = await manager.createSession({
+                title: `${registered.handle ?? instance.instanceId} session`,
+                ownerParticipant: participantId,
+                status: 'active',
+                metadata: { source: 'write-admission', instanceId: instance.instanceId, transport: instance.transport }
+            });
+            minted = created.id;
+            sessionId = created.id;
+        }
+    }
+    const caller = {
+        ...request.caller,
+        instanceId: instance.instanceId
+    };
+    if (sessionId)
+        caller.sessionId = sessionId;
+    if (participantId)
+        caller.participantId = participantId;
+    const settle = async (succeeded) => {
+        if (!succeeded) {
+            if (minted)
+                await manager.archiveSession(minted);
+            return;
+        }
+        if (!sessionId || !participantId)
+            return;
+        await manager.ensureInstanceMembership({ instanceId: instance.instanceId, sessionId, participantId });
+        if (!named)
+            await manager.setInstanceSession(instance.instanceId, sessionId);
+    };
+    return { caller, settle };
+}
+//# sourceMappingURL=admit-caller.js.map

package/dist/admission/admit-caller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit-caller.js","sourceRoot":"","sources":["../../src/admission/admit-caller.ts"],"names":[],"mappings":"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"}

package/dist/cli/services/session/sessions.d.ts

@@ -43,7 +43,7 @@ export declare function executeSessionInit(input: SessionInitInput, context: Ses
             source: string;
             role: string;
         }[] | undefined;
-        parentSessionId?: string | undefined;
+        parentSessionId?: string | null | undefined;
         assignedParticipant?: string | undefined;
         pausedAt?: Date | undefined;
         archivedAt?: Date | undefined;
@@ -96,7 +96,7 @@ export declare function executeSessionStatus(_input: SessionStatusInput, context
             source: string;
             role: string;
         }[] | undefined;
-        parentSessionId?: string | undefined;
+        parentSessionId?: string | null | undefined;
         assignedParticipant?: string | undefined;
         pausedAt?: Date | undefined;
         archivedAt?: Date | undefined;
@@ -133,7 +133,7 @@ export declare function executeSessionStatus(_input: SessionStatusInput, context
                 source: string;
                 role: string;
             }[] | undefined;
-            parentSessionId?: string | undefined;
+            parentSessionId?: string | null | undefined;
             assignedParticipant?: string | undefined;
             pausedAt?: Date | undefined;
             archivedAt?: Date | undefined;
@@ -228,7 +228,7 @@ export declare function executeSessionResume(input: SessionResumeInput, context:
             source: string;
             role: string;
         }[] | undefined;
-        parentSessionId?: string | undefined;
+        parentSessionId?: string | null | undefined;
         assignedParticipant?: string | undefined;
         pausedAt?: Date | undefined;
         archivedAt?: Date | undefined;

package/dist/cli/services/session.cli.consumer.d.ts

@@ -40,7 +40,7 @@ export declare function executeSessionInit(input: SessionInitInput, context: Ses
             source: string;
             role: string;
         }[] | undefined;
-        parentSessionId?: string | undefined;
+        parentSessionId?: string | null | undefined;
         assignedParticipant?: string | undefined;
         pausedAt?: Date | undefined;
         archivedAt?: Date | undefined;

package/dist/events/session.message-arrived.event.descriptor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `session.message.arrived`: a message addressed to an instance this runtime
+ * hosts has arrived, whichever process wrote it. A host that keeps a seat open
+ * subscribes (`runtime.hooks('session').on('messageArrived', …)`) to deliver it
+ * into the seat instead of polling the room.
+ */
+import { z } from 'zod/v4';
+import { VibesRuntime } from '@vibesdotdev/kernel';
+export declare const SESSION_MESSAGE_ARRIVED_NAMESPACE = "session";
+export declare const SESSION_MESSAGE_ARRIVED_EVENT_NAME = "messageArrived";
+export declare const SESSION_MESSAGE_ARRIVED_EVENT_ID = "session.message.arrived";
+export declare const SessionMessageArrivedEventSchema: z.ZodObject<{
+    instanceId: z.ZodString;
+    sessionId: z.ZodString;
+    messageId: z.ZodString;
+    fromParticipant: z.ZodString;
+    fromSlug: z.ZodString;
+    toParticipant: z.ZodString;
+    messageType: z.ZodString;
+    content: z.ZodString;
+    createdAt: z.ZodString;
+    runtime: z.ZodInstanceOf<VibesRuntime>;
+}, z.core.$strip>;
+export type SessionMessageArrivedEvent = z.infer<typeof SessionMessageArrivedEventSchema>;
+export declare const sessionMessageArrivedEvent: {
+    kind: "runtime/event";
+    id: string;
+    source: string;
+    name: string;
+    description: string;
+    trigger: string;
+};
+export default sessionMessageArrivedEvent;
+//# sourceMappingURL=session.message-arrived.event.descriptor.d.ts.map

package/dist/events/session.message-arrived.event.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.message-arrived.event.descriptor.d.ts","sourceRoot":"","sources":["../../src/events/session.message-arrived.event.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAsB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEvE,eAAO,MAAM,iCAAiC,YAAY,CAAC;AAC3D,eAAO,MAAM,kCAAkC,mBAAmB,CAAC;AACnE,eAAO,MAAM,gCAAgC,4BAA4B,CAAC;AAE1E,eAAO,MAAM,gCAAgC;;;;;;;;;;;iBAc3C,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,eAAO,MAAM,0BAA0B;;;;;;;CAOrC,CAAC;AAEH,eAAe,0BAA0B,CAAC"}

package/dist/events/session.message-arrived.event.descriptor.js

@@ -0,0 +1,36 @@
+/**
+ * `session.message.arrived`: a message addressed to an instance this runtime
+ * hosts has arrived, whichever process wrote it. A host that keeps a seat open
+ * subscribes (`runtime.hooks('session').on('messageArrived', …)`) to deliver it
+ * into the seat instead of polling the room.
+ */
+import { z } from 'zod/v4';
+import { createRuntimeAsset, VibesRuntime } from '@vibesdotdev/kernel';
+export const SESSION_MESSAGE_ARRIVED_NAMESPACE = 'session';
+export const SESSION_MESSAGE_ARRIVED_EVENT_NAME = 'messageArrived';
+export const SESSION_MESSAGE_ARRIVED_EVENT_ID = 'session.message.arrived';
+export const SessionMessageArrivedEventSchema = z.object({
+    /** The hosted instance the message is for. */
+    instanceId: z.string(),
+    sessionId: z.string(),
+    messageId: z.string(),
+    fromParticipant: z.string(),
+    /** The sender's display slug, so a woken seat can attribute who said what. */
+    fromSlug: z.string(),
+    toParticipant: z.string(),
+    messageType: z.string(),
+    content: z.string(),
+    createdAt: z.string(),
+    /** The runtime hosting the instance, so subscribers act on the right one. */
+    runtime: z.instanceof(VibesRuntime)
+});
+export const sessionMessageArrivedEvent = createRuntimeAsset({
+    kind: 'runtime/event',
+    id: SESSION_MESSAGE_ARRIVED_EVENT_ID,
+    source: SESSION_MESSAGE_ARRIVED_NAMESPACE,
+    name: 'Session Message Arrived',
+    description: 'Emitted when a message addressed to an instance this runtime hosts arrives, whichever process wrote it.',
+    trigger: 'custom'
+});
+export default sessionMessageArrivedEvent;
+//# sourceMappingURL=session.message-arrived.event.descriptor.js.map

package/dist/events/session.message-arrived.event.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.message-arrived.event.descriptor.js","sourceRoot":"","sources":["../../src/events/session.message-arrived.event.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEvE,MAAM,CAAC,MAAM,iCAAiC,GAAG,SAAS,CAAC;AAC3D,MAAM,CAAC,MAAM,kCAAkC,GAAG,gBAAgB,CAAC;AACnE,MAAM,CAAC,MAAM,gCAAgC,GAAG,yBAAyB,CAAC;AAE1E,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CAAC;IACxD,8CAA8C;IAC9C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE;IAC3B,8EAA8E;IAC9E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,6EAA6E;IAC7E,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC;CACnC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,0BAA0B,GAAG,kBAAkB,CAAC;IAC5D,IAAI,EAAE,eAAe;IACrB,EAAE,EAAE,gCAAgC;IACpC,MAAM,EAAE,iCAAiC;IACzC,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EAAE,yGAAyG;IACtH,OAAO,EAAE,QAAQ;CACjB,CAAC,CAAC;AAEH,eAAe,0BAA0B,CAAC"}

package/dist/manager.d.ts

@@ -16,7 +16,7 @@ import type { RuntimeInvokeCaller } from '@vibesdotdev/kernel/schemas/invoke-cal
 import type { VibesLink } from '@vibesdotdev/shared/schemas';
 import { type HarnessSeat, type HarnessSeatRegistration } from './schemas/harness-seat.ts';
 import type { SessionMembershipLease } from './storage/session-membership-leases.record.descriptor.ts';
-import type { Session, SessionCreate, SessionUpdate, SessionFilters, SessionSummary, Todo, TodoCreate, TodoUpdate, TodoFilters, TodoWithComputed, ScratchpadEntry, ScratchpadEntryCreate, ScratchpadEntryUpdate, ScratchpadFilters, ScratchpadSummary, JobRef, JobRefCreate, JobRefUpdate, JobFilters, JobSummary, ParticipantMessage, ParticipantMessageCreate, MessageFilters, ParticipantProfile, ParticipantProfileCreate, ParticipantProfileUpdate, ParticipantFilters, ParticipantConnection, KnowledgeRef, KnowledgeRefCreate, KnowledgeRefFilters, SessionPresence, SessionPresenceSummary } from './schemas/index.ts';
+import type { Session, SessionCreate, SessionUpdate, SessionFilters, SessionSummary, Todo, TodoCreate, TodoUpdate, TodoFilters, TodoWithComputed, ScratchpadEntry, ScratchpadEntryCreate, ScratchpadEntryUpdate, ScratchpadFilters, ScratchpadSummary, JobRef, JobRefCreate, JobRefUpdate, JobFilters, JobSummary, ParticipantMessage, ParticipantMessageCreate, MessageFilters, ParticipantProfile, ParticipantProfileCreate, ParticipantProfileUpdate, ParticipantFilters, ParticipantConnection, RegisterInstanceInput, KnowledgeRef, KnowledgeRefCreate, KnowledgeRefFilters, SessionPresence, SessionPresenceSummary } from './schemas/index.ts';
 /**
  * Key-order-independent JSON so metadata comparison can't flake on insertion
  * order: every object's keys are emitted sorted, arrays keep their order, and
@@ -154,6 +154,13 @@ export declare class SessionManager {
     }): Promise<Session>;
     getSession(id: string): Promise<Session | null>;
     updateSession(id: string, updates: SessionUpdate): Promise<void>;
+    /**
+     * Place a session under a parent session (a subsession), or make it top
+     * level with `null`. The parent must exist, and may not be the session itself
+     * or any of its descendants: a cycle is refused `INVALID_INPUT
+     * session-parent-cycle`.
+     */
+    setSessionParent(sessionId: string, parentSessionId: string | null): Promise<void>;
     /**
      * Bump a session's activity clock to reflect real traffic (messages), so
      * `lastActivityAt` tracks when the session was last USED — not merely when its
@@ -395,6 +402,96 @@ export declare class SessionManager {
     pruneOrphanedParticipantProfiles(): Promise<PruneOrphanedProfilesResult>;
     recordConnection(connection: Omit<ParticipantConnection, 'connectedAt' | 'disconnectedAt'>): Promise<ParticipantConnection>;
     closeConnection(connectionId: string): Promise<void>;
+    private static readonly INSTANCE_TTL_MS;
+    private static readonly INSTANCE_HEARTBEAT_MS;
+    /** Touches inside this window are not rewritten: one write per instance per window. */
+    private static readonly INSTANCE_TOUCH_MIN_MS;
+    private static readonly INSTANCE_HANDLE_ATTEMPTS;
+    /** This host's own key: distinguishes its in-process seats from another host's. */
+    readonly hostKey: string;
+    private readonly hostedInstances;
+    private readonly instanceTouchedAt;
+    /** Handles of instances this host registered, so a touch need not reread them. */
+    private readonly instanceHandles;
+    /** (instance, session, participant) triples this host has already leased. */
+    private readonly instanceMemberships;
+    private instanceHeartbeat?;
+    private static readonly INSTANCE_DELIVERY_MS;
+    /** Per hosted instance: messages newer than this have not been announced yet. */
+    private readonly deliveryCursors;
+    private instanceDelivery?;
+    private deliveryInFlight;
+    private static isLiveInstance;
+    private static randomHandle;
+    /**
+     * Register (or re-register) a running instance and give it a handle. A
+     * chosen handle held by another LIVE instance is refused `CONFLICT
+     * instance-handle-taken` naming the holder; one held by an expired or closed
+     * instance is reclaimed. With no choice the instance keeps its live handle,
+     * else gets a random `<agent>-<4>` handle. Uniqueness is the storage index
+     * on `activeHandle`, not this check: a lost race is retried (random) or
+     * refused (chosen).
+     */
+    registerInstance(input: RegisterInstanceInput): Promise<ParticipantConnection>;
+    /** Free `handle` when its holder is no longer live, so a new instance can take it. */
+    private releaseExpiredHandle;
+    /** The live instance holding `handle`, if any. */
+    liveInstanceByHandle(handle: string): Promise<ParticipantConnection | null>;
+    /**
+     * Mark an instance alive now and renew the membership leases it holds.
+     * Writes at most once per touch window per instance.
+     */
+    touchInstance(instanceId: string, options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Keep an admitted caller's instance live: register it the first time this
+     * host sees it (or after it was closed), otherwise touch it.
+     */
+    ensureInstance(input: RegisterInstanceInput): Promise<{
+        handle?: string;
+    }>;
+    /**
+     * Make an instance a member of the session it calls with: one lease keyed
+     * on the instance, taken the first time this host sees the pair and renewed
+     * by every touch after. An archived or missing session takes no member.
+     */
+    ensureInstanceMembership(input: {
+        instanceId: string;
+        sessionId: string;
+        participantId: string;
+    }): Promise<void>;
+    /**
+     * Give a live instance the handle it chose. The registry's uniqueness rule
+     * applies: a handle another live instance holds is refused naming its holder.
+     */
+    chooseInstanceHandle(instanceId: string, handle: string): Promise<ParticipantConnection>;
+    /** One instance's registry row. */
+    getInstance(instanceId: string): Promise<ParticipantConnection | null>;
+    /** Record the session an instance is working in (its bind, or its first write). */
+    setInstanceSession(instanceId: string, sessionId: string): Promise<void>;
+    /** The session an instance is working in, while that session is still open. */
+    instanceSession(instanceId: string): Promise<string | undefined>;
+    /** Close an instance: it stops being live, frees its handle and releases its leases. */
+    closeInstance(instanceId: string): Promise<void>;
+    /** Every live instance in this store: who is here, however they arrived. */
+    listLiveInstances(): Promise<ParticipantConnection[]>;
+    private forgetInstance;
+    private unreleasedLeasesOf;
+    /**
+     * Heartbeat hosted instances on this runtime's lifecycle interval, so the
+     * kernel stops it at disposal. A finite host (a one-shot command) runs no
+     * interval: its instance lives by activity and closes with the manager.
+     */
+    private hostInstance;
+    private stopInstanceHeartbeat;
+    /**
+     * Announce, on this runtime's `session` hook bus, every message addressed to
+     * a hosted instance's participant that arrived since the last check, whichever
+     * process wrote it (`session.message.arrived`). Starts from the moment the
+     * instance was hosted, so history is never replayed as new.
+     */
+    announceArrivedMessages(): Promise<number>;
     getConnectionHistory(participantId?: string, limit?: number): Promise<ParticipantConnection[]>;
     addKnowledgeRef(sessionId: string, ref: KnowledgeRefCreate): Promise<KnowledgeRef>;
     getKnowledgeRef(id: string): Promise<KnowledgeRef | null>;
@@ -475,7 +572,7 @@ export declare class SessionManager {
                 source: string;
                 role: string;
             }[] | undefined;
-            parentSessionId?: string | undefined;
+            parentSessionId?: string | null | undefined;
             assignedParticipant?: string | undefined;
             pausedAt?: Date | undefined;
             archivedAt?: Date | undefined;