AiSessionHandle

interface

A live handle to one durable AI session. A session owns a conversation: its history, its model, its working directory, and its place in the session tree. Handles are cheap and addressable, so holding one across turns is normal. Sessions relate to each other two ways. AiSessionHandle.spawn starts a fresh child with no history. AiSessionHandle.fork copies this session's conversation up to now and continues independently. Use `spawn` for unrelated work, `fork` when the child needs the context you already built.

interface AiSessionHandle

Import

import { AiSessionHandle } from '@modular/sdk';

Members13

id: string & $brand<'SessionId'>
Stable identifier for this session.
lineage: AiSessionLineage
How this session came to exist: root, spawned, or forked.
resource: string
Canonical URI addressing this session.
children: () => Promise<readonly AiSessionHandle[]>
Sessions spawned or forked from this one.
fork: (config?: AiSessionForkConfig) => Promise<AiSessionHandle>
Copy this conversation into a new session that continues independently. The child sees everything said up to now; nothing said in either session afterwards reaches the other.
getTurn: (submissionId: string) => AiTurnHandle
Re-acquire a handle to a turn you started earlier.
metadata: () => Promise<AiSessionMetadata>
Current title, model, status, and working directory.
notify: (notification: Omit<AiNotificationMessage, 'type'>) => Promise<AiTurnHandle>
Shorthand for `send({ type: 'notification', ... })`. The message arrives tagged as a system event, not as something the user said, which is how background work reports back without impersonating the user.
onProgress: (listener: (signal: AiSessionSignal) => void) => Disposable
Observe everything this session emits: text, reasoning, tool calls, turn completion. Dispose the returned handle to stop listening.
parent: () => Promise<AiSessionHandle | null>
The session this one was spawned or forked from, or `null` for a root.
run: (prompt: string, options?: AiSendOptions) => Promise<AiRunResult> | <T>(prompt: string, options?: AiSendOptions) => Promise<T>
Send a prompt and wait for the finished answer. The generic overload validates the reply against `T` and rejects if the model returns something that does not match, so a caller never has to parse prose.
send: (message: AiMessage, options?: AiSendOptions) => Promise<AiTurnHandle>
Put a message into this session. The message's `type` says what kind of thing it is. Who produced it is stamped by the host from the calling context, so a mod cannot claim to be the user or another mod. Both kinds drive a turn in the session.
spawn: (config?: AiSessionConfig) => Promise<AiSessionHandle>
Start a child session with no conversation history. Inherits this session's model and working directory unless `config` overrides them.

Notes

example: ```ts const child = await ctx.session.fork(); await child.run('Audit the auth middleware for missing checks.'); const summary = await child.run('Summarize what you just did.'); await ctx.session.notify({ title: 'Audit finished', body: `${summary.text}\n\nSession ${child.id}`, }); ```
category: AI