@borgee/agents-host 0.2.97 → 0.2.110

package/dist/providers/normalized/control-policy.d.ts

@@ -0,0 +1,5 @@
+import type { AgentInteractionResponse } from '../../native-providers.js';
+/** Host grants cannot outlive the exact tool request or native turn. */
+export declare function assertHostedInteractionScope(response: AgentInteractionResponse): void;
+/** Only provider-classified ownership errors are safe to publish verbatim. */
+export declare function nativeSessionFailureMessage(error: unknown): string;

package/dist/providers/normalized/control-policy.js

@@ -0,0 +1,12 @@
+import { AgentSessionInUseError } from '../../native-providers.js';
+/** Host grants cannot outlive the exact tool request or native turn. */
+export function assertHostedInteractionScope(response) {
+    if ((response.kind === 'tool_approval' && response.decision === 'allow' && response.scope !== 'once')
+        || (response.kind === 'permission_approval' && response.decision === 'allow' && response.scope !== 'turn')) {
+        throw new Error('Host permissions cannot be widened beyond this interaction or turn.');
+    }
+}
+/** Only provider-classified ownership errors are safe to publish verbatim. */
+export function nativeSessionFailureMessage(error) {
+    return error instanceof AgentSessionInUseError ? error.message : 'The native session could not accept this operation. Check the native runtime before retrying.';
+}

package/dist/providers/normalized/interactions.d.ts

@@ -0,0 +1,3 @@
+import { type ServerRequestContext } from '../../plugin-sdk.js';
+import type { ProviderAdapter } from '../provider-adapter.js';
+export declare function respondToHostedInteraction(provider: ProviderAdapter, action: string, params: unknown, context?: ServerRequestContext): Promise<unknown>;

package/dist/providers/normalized/interactions.js

@@ -0,0 +1,39 @@
+import { parseSessionManagementRequest, parseSessionDescriptionRequest, parseSessionObservationRequest, parseSessionDirectoryRequest } from '../../plugin-sdk.js';
+import { isInteractionResponseMessage, PROTOCOL_VERSION } from '../../native-providers.js';
+export async function respondToHostedInteraction(provider, action, params, context) {
+    if (action === 'describe_session_management' && context)
+        return provider.describeSessionManagement?.() ?? { operations: [] };
+    if (['discover_sessions', 'create_session', 'open_session'].includes(action) && provider.manageSession && context)
+        return provider.manageSession(parseSessionManagementRequest(params), context);
+    if (action === 'list_sessions' && provider.listSessions && context)
+        return provider.listSessions(parseSessionDirectoryRequest(params), context);
+    if (action === 'describe_session' && provider.describeSession && context)
+        return provider.describeSession(parseSessionDescriptionRequest(params), context) ?? null;
+    if (action === 'session_observation' && provider.observeSession && context)
+        return provider.observeSession(parseSessionObservationRequest(params), context);
+    if (action === 'sync_normalized_activity') {
+        if (!params || typeof params !== 'object' || !('channel_id' in params) || typeof params.channel_id !== 'string' || !params.channel_id)
+            throw new Error('Invalid normalized activity target.');
+        return { synced: provider.syncNormalizedActivity?.(params.channel_id) ?? false };
+    }
+    const input = params && typeof params === 'object' ? params : undefined;
+    const fields = ['binding_id', 'native_session_id', 'connection_generation'];
+    const targeted = !!input && fields.some(field => field in input);
+    if (targeted && (!fields.every(field => typeof input[field] === 'string' && /^[A-Za-z0-9_:.@/-]{1,512}$/.test(input[field])) || !context?.isConnectionCurrent?.()))
+        throw new Error('Invalid native Session target.');
+    const binding = targeted ? input : undefined;
+    if (action === 'stop_turn') {
+        if (!input || typeof input.channel_id !== 'string' || !input.channel_id)
+            throw new Error('Invalid native stop target.');
+        return { aborted: await provider.cancelTurn?.(input.channel_id, binding, context) ?? false };
+    }
+    if (action !== 'interaction_response' || !provider.respondInteraction)
+        throw new Error('Unsupported native Host request.');
+    if (!params || typeof params !== 'object')
+        throw new Error('Invalid native Host request.');
+    if (!input || typeof input.channel_id !== 'string' || (typeof input.task_id !== 'string' && !binding) || !isInteractionResponseMessage(input.body))
+        throw new Error('Invalid native interaction envelope.');
+    const { agentId, requestId, response } = input.body.payload;
+    const receipt = await provider.respondInteraction({ channelId: input.channel_id, taskId: typeof input.task_id === 'string' ? input.task_id : undefined, agentId, requestId, response, binding }, context);
+    return { protocolVersion: PROTOCOL_VERSION, type: 'interaction_resolved', payload: { agentId, requestId, response: receipt } };
+}

package/dist/providers/normalized/legacy-input-ownership.d.ts

@@ -0,0 +1,34 @@
+import type { AgentMessageReceipt, ProviderObservation } from '../../native-providers.js';
+interface LegacyPublicInput {
+    text: string | null;
+    prompt: string;
+    clientMessageId?: string;
+}
+export interface OwnedObservation<T> {
+    owner: T;
+    observation: ProviderObservation;
+}
+/** Matches accepted native input identities before any task-scoped publication. */
+export declare class InputOwnership<T> {
+    private readonly allowReceiptless;
+    constructor(allowReceiptless?: boolean);
+    private readonly inputs;
+    private pending;
+    private pendingBytes;
+    private readonly publicInputs;
+    private publicInputBytes;
+    get size(): number;
+    has(owner: T): boolean;
+    owners(): T[];
+    register(owner: T, publicInput?: LegacyPublicInput): void;
+    remove(owner: T): void;
+    settle(owner: T, receipt: void | AgentMessageReceipt): OwnedObservation<T>[];
+    /** Preserve the legacy display-body contract before the shared canonical formatter. */
+    publicObservation(observation: ProviderObservation, owner?: T): ProviderObservation;
+    turnId(owner: T): string | undefined;
+    retireObservations(): void;
+    /** History can confirm a receipt identity, but cannot claim a receipt-less input. */
+    recover(owner: T, observations: readonly ProviderObservation[]): string | undefined;
+    observe(observation: ProviderObservation): OwnedObservation<T>[];
+}
+export {};

package/dist/providers/normalized/legacy-input-ownership.js

@@ -0,0 +1,123 @@
+/** Matches accepted native input identities before any task-scoped publication. */
+export class InputOwnership {
+    allowReceiptless;
+    constructor(allowReceiptless = false) {
+        this.allowReceiptless = allowReceiptless;
+    }
+    inputs = new Map();
+    pending = [];
+    pendingBytes = 0;
+    publicInputs = new Map();
+    publicInputBytes = 0;
+    get size() { return this.inputs.size; }
+    has(owner) { return this.inputs.has(owner); }
+    owners() { return [...this.inputs.keys()]; }
+    register(owner, publicInput) {
+        if (this.inputs.size >= 32)
+            throw new Error('Too many pending native input associations.');
+        this.inputs.set(owner, { owner, settled: false, publicInput });
+    }
+    remove(owner) {
+        this.inputs.delete(owner);
+        if (!this.inputs.size) {
+            this.pending = [];
+            this.pendingBytes = 0;
+        }
+    }
+    settle(owner, receipt) {
+        const input = this.inputs.get(owner);
+        if (!input)
+            return [];
+        input.settled = true;
+        input.receipt = receipt || undefined;
+        input.turnId = receipt?.turnId;
+        const pending = this.pending;
+        this.pending = [];
+        this.pendingBytes = 0;
+        const result = [];
+        for (const observation of pending)
+            result.push(...this.observe(observation));
+        return result;
+    }
+    /** Preserve the legacy display-body contract before the shared canonical formatter. */
+    publicObservation(observation, owner) {
+        const event = observation.event;
+        if (event.type !== 'timeline' || event.item.type !== 'user_message')
+            return observation;
+        const item = event.item;
+        const input = owner === undefined ? undefined : this.inputs.get(owner);
+        if (input?.settled && input.publicInput && item.messageId && event.turnId === input.turnId) {
+            const proven = input.receipt?.messageId === item.messageId || !input.receipt?.messageId && !item.clientMessageId
+                && (input.publicMessageId === item.messageId || !input.publicMessageId && item.text === input.publicInput.prompt);
+            if (proven && !this.publicInputs.has(item.messageId)) {
+                const display = { text: input.publicInput.text, clientMessageId: input.publicInput.clientMessageId };
+                const bytes = Buffer.byteLength(JSON.stringify([item.messageId, display]));
+                if (this.publicInputs.size < 4096 && this.publicInputBytes + bytes <= 1048576) {
+                    input.publicMessageId = item.messageId;
+                    this.publicInputs.set(item.messageId, display);
+                    this.publicInputBytes += bytes;
+                }
+            }
+        }
+        const verified = item.messageId ? this.publicInputs.get(item.messageId) : undefined;
+        return { ...observation, event: { ...event, item: { type: 'user_message',
+                    ...(item.messageId ? { messageId: item.messageId } : {}), text: verified?.text ?? 'Input content unavailable.',
+                    ...(verified?.text != null && verified.clientMessageId ? { clientMessageId: verified.clientMessageId } : {}) } } };
+    }
+    turnId(owner) { return this.inputs.get(owner)?.turnId; }
+    retireObservations() { this.pending = []; this.pendingBytes = 0; }
+    /** History can confirm a receipt identity, but cannot claim a receipt-less input. */
+    recover(owner, observations) {
+        const input = this.inputs.get(owner);
+        if (!input?.settled || !input.receipt)
+            return;
+        const matches = new Set(observations.flatMap(({ event }) => event.type === 'timeline' && event.item.type === 'user_message'
+            && input.receipt?.messageId && event.item.messageId === input.receipt.messageId && event.turnId ? [event.turnId] : []));
+        if (matches.size > 1 || input.turnId && matches.size && !matches.has(input.turnId))
+            return;
+        const turnId = input.turnId ?? [...matches][0];
+        if (!turnId || [...this.inputs.values()].some(other => other !== input && other.turnId === turnId))
+            return;
+        input.turnId = turnId;
+        return turnId;
+    }
+    observe(observation) {
+        const event = observation.event;
+        const turnId = 'turnId' in event ? event.turnId : undefined;
+        if (!turnId)
+            return [];
+        let input = [...this.inputs.values()].find(value => value.settled && value.turnId === turnId);
+        if (event.type === 'timeline' && event.item.type === 'user_message' && event.item.messageId) {
+            const messageId = event.item.messageId;
+            const byMessage = [...this.inputs.values()].find(value => value.settled && value.receipt?.messageId === messageId);
+            if (byMessage) {
+                if (input && input !== byMessage)
+                    throw new Error('Native input has conflicting message and turn ownership.');
+                if (byMessage.turnId && byMessage.turnId !== turnId)
+                    return [];
+                input = byMessage;
+                input.turnId = turnId;
+            }
+        }
+        if (this.allowReceiptless && !input && ['turn_started', 'turn_canceled', 'turn_failed'].includes(event.type)) {
+            // Receipt-less SDK implementations keep their existing ordinary-send contract.
+            input = [...this.inputs.values()].find(value => value.settled && !value.receipt && !value.turnId);
+            if (input)
+                input.turnId = turnId;
+        }
+        if (input) {
+            const ready = this.pending.filter(value => 'turnId' in value.event && value.event.turnId === turnId);
+            this.pending = this.pending.filter(value => !ready.includes(value));
+            this.pendingBytes = this.pending.reduce((size, value) => size + Buffer.byteLength(JSON.stringify(value)), 0);
+            return [...ready.map(value => ({ owner: input.owner, observation: value })), { owner: input.owner, observation }];
+        }
+        if ([...this.inputs.values()].some(value => !value.settled || (value.receipt?.messageId && !value.turnId))) {
+            const bytes = Buffer.byteLength(JSON.stringify(observation));
+            if (this.pending.length >= 256 || this.pendingBytes + bytes > 1048576)
+                throw new Error('Native input identity observation buffer exceeded.');
+            this.pending.push(observation);
+            this.pendingBytes += bytes;
+        }
+        return [];
+    }
+}

package/dist/providers/normalized/session-management.d.ts

@@ -0,0 +1,67 @@
+import type { AgentPersistenceHandle, AgentProviderAdapter, AgentSession } from '../../native-providers.js';
+import type { NativeSessionDirectory, SessionDiscoveryRequest, SessionMutationRequest, SessionManagementReceipt, SessionControlTarget, ServerRequestContext } from '../../plugin-sdk.js';
+import type { CodexChannelSessionStore } from '../codex/session-store.js';
+interface CatalogRow {
+    nativeSessionId: string;
+    workspace?: string;
+    title: string;
+    updatedAt: string;
+    state: string;
+    parentNativeSessionId?: string;
+    lineageUnavailable?: true;
+}
+interface CatalogProvider extends AgentProviderAdapter {
+    listSessions(options: {
+        cursor?: string;
+        limit: number;
+        includeAllSources: true;
+    }): Promise<{
+        sessions: CatalogRow[];
+        nextCursor?: string;
+    }>;
+    inspectSession(nativeId: string): Promise<CatalogRow>;
+}
+interface Admission {
+    target: SessionControlTarget;
+    workspace_path: string;
+}
+type LoadedAdmission = Admission & {
+    persistence?: AgentPersistenceHandle;
+};
+export interface HostSessionManagementOptions {
+    root?: string;
+    provider: CatalogProvider;
+    store: CodexChannelSessionStore;
+    resolveAgentId(): string | undefined;
+    serverUrl: string;
+    loadProtectedNativeIds(): Promise<Set<string>>;
+    withOwnershipLock?<T>(work: () => Promise<T>): Promise<T>;
+    find(nativeId: string, channelId: string, generation: string): LoadedAdmission | undefined | Promise<LoadedAdmission | undefined>;
+    register(session: AgentSession, channelId: string, cwd: string, generation: string, current: () => boolean): Promise<Admission>;
+}
+export declare function allocateSessionWorkspace(root: string, date?: Date): Promise<string>;
+/** Native admission shares the Host registry but never selects a channel default. */
+export declare class HostSessionManagement {
+    private readonly options;
+    private admission;
+    private readonly uncommittedClaims;
+    private readonly cursors;
+    private generation?;
+    private knownClaims;
+    canExpose(nativeId: string, agentId: string, channelId: string): boolean;
+    constructor(options: HostSessionManagementOptions);
+    private current;
+    private claims;
+    private commitClaims;
+    private owned;
+    withAdmission<T>(work: () => Promise<T>): Promise<T>;
+    assertUnclaimed(nativeId: string): Promise<void>;
+    /** All observer admission paths share the durable independent identity reservation. */
+    admitUnclaimed<T>(nativeId: string, work: () => Promise<T>): Promise<T | undefined>;
+    private lineageReason;
+    operations(): Promise<Array<'discover_sessions' | 'create_session' | 'open_session'>>;
+    discover(request: SessionDiscoveryRequest, context: ServerRequestContext): Promise<NativeSessionDirectory>;
+    mutate(request: SessionMutationRequest, context: ServerRequestContext): Promise<SessionManagementReceipt>;
+    private admit;
+}
+export {};

package/dist/providers/normalized/session-management.js

@@ -0,0 +1,334 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { lstat, mkdir, realpath, stat } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { AgentSessionInUseError } from '../../native-providers.js';
+export async function allocateSessionWorkspace(root, date = new Date()) {
+    if (!isAbsolute(root))
+        throw new Error('session_workspace_unavailable');
+    const canonical = await realpath(root);
+    if (!(await stat(canonical)).isDirectory())
+        throw new Error('session_workspace_unavailable');
+    const pad = (value) => String(value).padStart(2, '0');
+    const day = join(canonical, `${pad(date.getFullYear() % 100)}${pad(date.getMonth() + 1)}${pad(date.getDate())}`);
+    try {
+        await mkdir(day, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    if ((await lstat(day)).isSymbolicLink() || await realpath(day) !== day)
+        throw new Error('session_workspace_containment_failed');
+    for (let attempt = 0; attempt < 16; attempt++) {
+        const path = join(day, `${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}${randomBytes(5).toString('hex')}`);
+        try {
+            await mkdir(path, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                continue;
+            throw error;
+        }
+        if (await realpath(day) !== day || await realpath(path) !== path)
+            throw new Error('session_workspace_containment_failed');
+        return path;
+    }
+    throw new Error('session_workspace_capacity');
+}
+function route(request) {
+    return { agent_id: request.agent_id, channel_id: request.channel_id, connection_generation: request.connection_generation };
+}
+/** Native admission shares the Host registry but never selects a channel default. */
+export class HostSessionManagement {
+    options;
+    admission = Promise.resolve();
+    uncommittedClaims = new Map();
+    cursors = new Map();
+    generation;
+    knownClaims = Object.create(null);
+    canExpose(nativeId, agentId, channelId) {
+        const claim = this.knownClaims[nativeId] ?? this.uncommittedClaims.get(nativeId);
+        return !claim || this.owned(claim, { agent_id: agentId, channel_id: channelId });
+    }
+    constructor(options) {
+        this.options = options;
+    }
+    current(request, context) {
+        return request.agent_id === this.options.resolveAgentId() && !context.signal.aborted && context.isConnectionCurrent?.() !== false && Date.now() < request.deadline_at;
+    }
+    async claims() {
+        const rows = await this.options.store.load(this.options.resolveAgentId());
+        const result = Object.create(null);
+        for (const [id, text] of Object.entries(rows)) {
+            const value = JSON.parse(text);
+            if (!value || typeof value.agentId !== 'string' || typeof value.server !== 'string' || typeof value.channelId !== 'string' || typeof value.cwd !== 'string'
+                || value.handle?.sessionId !== id || value.handle.providerId !== 'codex' || typeof value.handle.opaque !== 'string')
+                throw new Error('session_ownership_unavailable');
+            result[id] = value;
+        }
+        for (const [id, claim] of this.uncommittedClaims) {
+            const committed = result[id];
+            if (committed && (committed.agentId !== claim.agentId || committed.channelId !== claim.channelId || committed.server !== claim.server || committed.cwd !== claim.cwd))
+                throw new Error('session_ownership_unavailable');
+            result[id] = claim;
+        }
+        this.knownClaims = result;
+        return result;
+    }
+    async commitClaims(claims, agentId) {
+        await this.options.store.save(agentId, Object.fromEntries(Object.entries(claims).map(([id, claim]) => [id, JSON.stringify(claim)])));
+        this.knownClaims = claims;
+        this.uncommittedClaims.clear();
+    }
+    owned(claim, request) {
+        return claim.agentId === request.agent_id && claim.channelId === request.channel_id && claim.server === this.options.serverUrl;
+    }
+    withAdmission(work) {
+        const run = () => this.options.withOwnershipLock ? this.options.withOwnershipLock(work) : work();
+        const result = this.admission.catch(() => { }).then(run);
+        this.admission = result;
+        return result;
+    }
+    async assertUnclaimed(nativeId) {
+        if ((await this.claims())[nativeId])
+            throw new Error('session_owned_elsewhere');
+    }
+    /** All observer admission paths share the durable independent identity reservation. */
+    async admitUnclaimed(nativeId, work) {
+        return this.withAdmission(async () => {
+            if ((await this.claims())[nativeId])
+                return undefined;
+            return work();
+        });
+    }
+    async lineageReason(row, claims, protectedIds, request, loaded) {
+        if (protectedIds.has(row.nativeSessionId))
+            return 'session_default_owned';
+        const claim = claims[row.nativeSessionId];
+        if (claim && !this.owned(claim, request))
+            return 'session_owned_elsewhere';
+        if (claim || loaded) {
+            if (loaded && (loaded.target.agent_id !== request.agent_id || loaded.target.channel_id !== request.channel_id
+                || loaded.target.connection_generation !== request.connection_generation || loaded.target.native_session_id !== row.nativeSessionId))
+                return 'session_native_identity_changed';
+            if (!claim && (!loaded?.persistence || loaded.persistence.sessionId !== row.nativeSessionId
+                || loaded.persistence.providerId !== 'codex' || typeof loaded.persistence.opaque !== 'string'))
+                return 'session_native_identity_changed';
+            try {
+                const cwd = row.workspace && await realpath(row.workspace);
+                if (!cwd || claim && cwd !== claim.cwd || loaded && cwd !== loaded.workspace_path)
+                    return 'session_native_identity_changed';
+            }
+            catch {
+                return 'session_native_identity_changed';
+            }
+            return undefined;
+        }
+        const seen = new Set();
+        for (let depth = 0; depth < 64; depth++) {
+            if (protectedIds.has(row.nativeSessionId))
+                return 'session_default_owned';
+            if (claims[row.nativeSessionId] && !this.owned(claims[row.nativeSessionId], request))
+                return 'session_owned_elsewhere';
+            if (row.lineageUnavailable || seen.has(row.nativeSessionId))
+                return 'session_lineage_unavailable';
+            seen.add(row.nativeSessionId);
+            if (!row.parentNativeSessionId)
+                return undefined;
+            const parentId = row.parentNativeSessionId;
+            try {
+                row = await this.options.provider.inspectSession(parentId);
+            }
+            catch {
+                return 'session_lineage_unavailable';
+            }
+            if (row.nativeSessionId !== parentId)
+                return 'session_lineage_unavailable';
+        }
+        return 'session_lineage_unavailable';
+    }
+    async operations() {
+        await this.claims();
+        await this.options.loadProtectedNativeIds();
+        return ['discover_sessions', 'open_session', ...(this.options.root ? ['create_session'] : [])];
+    }
+    async discover(request, context) {
+        if (!this.current(request, context))
+            throw new Error('stale_session_binding');
+        if (this.generation !== request.connection_generation) {
+            this.cursors.clear();
+            this.generation = request.connection_generation;
+        }
+        const query = JSON.stringify([request.agent_id, request.channel_id, request.actor_id, request.connection_generation, request.workspace_path ?? null, request.limit]);
+        let cursor;
+        let incomplete = false;
+        if (request.cursor) {
+            const saved = this.cursors.get(request.cursor);
+            if (!saved || saved.query !== query)
+                throw new Error('session_catalog_cursor_invalid');
+            if (saved.expires < Date.now())
+                throw new Error('session_catalog_cursor_expired');
+            cursor = saved.cursor;
+            incomplete = saved.incomplete;
+        }
+        const claims = await this.claims();
+        const protectedIds = await this.options.loadProtectedNativeIds();
+        let page;
+        try {
+            page = await this.options.provider.listSessions({ includeAllSources: true, limit: request.limit, ...(cursor ? { cursor } : {}) });
+        }
+        catch {
+            throw new Error('session_catalog_unavailable');
+        }
+        if (!this.current(request, context))
+            throw new Error('stale_session_binding');
+        const eligible = [];
+        for (const row of page.sessions) {
+            if (request.workspace_path && row.workspace !== request.workspace_path)
+                continue;
+            const loaded = await this.options.find(row.nativeSessionId, request.channel_id, request.connection_generation);
+            const reason = await this.lineageReason(row, claims, protectedIds, request, loaded);
+            if (reason === 'session_lineage_unavailable')
+                incomplete = true;
+            if (!reason)
+                eligible.push(row);
+        }
+        if (!this.current(request, context))
+            throw new Error('stale_session_binding');
+        const sessions = eligible.map(row => ({ native_session_id: row.nativeSessionId, title: row.title,
+            ...(row.workspace ? { workspace_path: row.workspace } : {}), updated_at: row.updatedAt,
+            state: row.state === 'running' || row.state === 'waiting' ? 'running' : row.state === 'idle' ? 'idle' : 'unknown' }));
+        if (!page.nextCursor)
+            return incomplete
+                ? { ...route(request), sessions, complete: false, limitation: 'source_incomplete' }
+                : { ...route(request), sessions, complete: true };
+        if (this.cursors.size >= 512)
+            return { ...route(request), sessions, complete: false, limitation: 'capacity_limit' };
+        const token = randomUUID();
+        this.cursors.set(token, { query, cursor: page.nextCursor, expires: Date.now() + 300_000, incomplete });
+        return { ...route(request), sessions, complete: false, next_cursor: token };
+    }
+    mutate(request, context) {
+        const allocation = { root: this.options.root, date: new Date() };
+        return this.withAdmission(() => this.admit(request, context, allocation)).catch(() => ({ ...route(request), operation_id: request.operation_id, status: 'rejected', reason: 'session_ownership_unavailable' }));
+    }
+    async admit(request, context, allocation) {
+        const base = { ...route(request), operation_id: request.operation_id };
+        const reject = (reason) => ({ ...base, status: 'rejected', reason });
+        if (!this.current(request, context))
+            return reject('stale_session_binding');
+        const claims = await this.claims();
+        const protectedIds = await this.options.loadProtectedNativeIds();
+        if (this.uncommittedClaims.size)
+            await this.commitClaims(claims, request.agent_id);
+        let cwd;
+        let nativeId;
+        if (request.action === 'open_session') {
+            if (request.target === 'channel_default')
+                return reject('session_default_open_unsupported');
+            nativeId = request.native_session_id;
+            if (protectedIds.has(nativeId))
+                return reject('session_default_owned');
+            const claim = claims[nativeId];
+            if (claim && !this.owned(claim, request))
+                return reject('session_owned_elsewhere');
+            let inspected;
+            try {
+                inspected = await this.options.provider.inspectSession(nativeId);
+            }
+            catch {
+                return reject('session_lineage_unavailable');
+            }
+            if (inspected.nativeSessionId !== nativeId)
+                return reject('session_lineage_unavailable');
+            const loaded = await this.options.find(nativeId, request.channel_id, request.connection_generation);
+            const lineage = await this.lineageReason(inspected, claims, protectedIds, request, loaded);
+            if (lineage)
+                return reject(lineage);
+            if (!this.current(request, context))
+                return reject('stale_session_binding');
+            if (loaded) {
+                if (claim && claim.cwd !== loaded.workspace_path)
+                    return reject('session_native_identity_changed');
+                if (!claim) {
+                    const handle = loaded.persistence;
+                    if (!handle || handle.sessionId !== nativeId || handle.providerId !== 'codex' || typeof handle.opaque !== 'string')
+                        return reject('session_native_identity_changed');
+                    claims[nativeId] = { agentId: request.agent_id, server: this.options.serverUrl, channelId: request.channel_id, cwd: loaded.workspace_path, handle };
+                    this.uncommittedClaims.set(nativeId, claims[nativeId]);
+                    try {
+                        await this.commitClaims(claims, request.agent_id);
+                    }
+                    catch {
+                        return { ...base, status: 'unconfirmed', reason: 'session_admission_unconfirmed', native_session_id: nativeId };
+                    }
+                    if (!this.current(request, context))
+                        return { ...base, status: 'unconfirmed', reason: 'stale_session_binding', native_session_id: nativeId };
+                }
+                return { ...base, status: 'confirmed', target: loaded.target, workspace_path: loaded.workspace_path };
+            }
+            if (claim)
+                cwd = claim.cwd;
+            else {
+                let cursor;
+                let found;
+                for (let scan = 0; scan < 64; scan++) {
+                    if (!this.current(request, context))
+                        return reject('stale_session_binding');
+                    const page = await this.options.provider.listSessions({ includeAllSources: true, limit: 100, ...(cursor ? { cursor } : {}) });
+                    found = page.sessions.find(row => row.nativeSessionId === nativeId);
+                    if (found || !page.nextCursor)
+                        break;
+                    cursor = page.nextCursor;
+                }
+                if (!found?.workspace)
+                    return reject('session_catalog_unavailable');
+                cwd = await realpath(found.workspace);
+            }
+        }
+        else {
+            if (!allocation.root)
+                return { ...base, status: 'unsupported', reason: 'session_workspace_unconfigured' };
+            try {
+                cwd = await allocateSessionWorkspace(allocation.root, allocation.date);
+            }
+            catch {
+                return reject('session_workspace_unavailable');
+            }
+        }
+        if (!this.current(request, context))
+            return reject('stale_session_binding');
+        let session;
+        let registered = false;
+        try {
+            session = request.action === 'open_session'
+                ? await this.options.provider.resumeSession({ providerId: 'codex', sessionId: nativeId, opaque: '{}' })
+                : await this.options.provider.createSession({ sessionId: randomUUID(), cwd });
+            const info = await session.runtimeInfo();
+            if (!info.sessionId || info.providerId !== 'codex' || nativeId && info.sessionId !== nativeId)
+                throw new Error('session_native_identity_changed');
+            nativeId = info.sessionId;
+            if (!info.cwd || await realpath(info.cwd) !== cwd || !info.persistence || info.persistence.sessionId !== nativeId || info.persistence.providerId !== 'codex')
+                throw new Error('session_native_identity_changed');
+            if (protectedIds.has(nativeId) || claims[nativeId] && !this.owned(claims[nativeId], request))
+                throw new Error('session_owned_elsewhere');
+            claims[nativeId] = { agentId: request.agent_id, server: this.options.serverUrl, channelId: request.channel_id, cwd, handle: info.persistence };
+            this.uncommittedClaims.set(nativeId, claims[nativeId]);
+            await this.commitClaims(claims, request.agent_id);
+            if (!this.current(request, context))
+                throw new Error('stale_session_binding');
+            const admitted = await this.options.register(session, request.channel_id, cwd, request.connection_generation, () => this.current(request, context));
+            registered = true;
+            return { ...base, status: 'confirmed', ...admitted };
+        }
+        catch (error) {
+            if (!session && error instanceof AgentSessionInUseError)
+                return reject('session_in_use');
+            return { ...base, status: 'unconfirmed', reason: 'session_admission_unconfirmed', ...(nativeId ? { native_session_id: nativeId } : {}) };
+        }
+        finally {
+            if (session && !registered)
+                await session.dispose().catch(() => { });
+        }
+    }
+}

package/dist/providers/normalized/session-ownership.d.ts

@@ -0,0 +1,3 @@
+/** Reads ownership evidence without initializing, migrating, or writing default stores. */
+export declare function readProtectedCodexSessions(stateRoot: string): Promise<Set<string>>;
+export declare function createSessionOwnershipLock(directory: string): <T>(work: () => Promise<T>) => Promise<T>;