LanguageModelSession

Manages conversation state and provides all generation methods — text, streaming, structured, and JSON Schema.

Constructor

new LanguageModelSession(options?: {
  instructions?: string;
  model?: SystemLanguageModel;
  tools?: Tool[];
})

Parameter	Default	Description
instructions	undefined	System prompt for the session
model	Default model	A configured SystemLanguageModel
tools	[]	Tools available during generation

Methods

respond()

Generate a text response.

respond(prompt: string | PromptInput, options?: {
  options?: GenerationOptions
}): Promise<string>

Prompt attachments macOS 27

Every method that takes a prompt accepts either a string or PromptInput:

interface PromptInput {
  text: string;
  attachments?: { path: string; label?: string }[];
}

await session.respond({
  text: "What is in this picture?",
  attachments: [{ path: "/tmp/chart.png", label: "quarterly chart" }],
});

Attachments require macOS 27 at runtime, and a native library built against the macOS 27 SDK. The bundled library is built on macOS 26, so today every attachment is rejected with a PromptAttachmentError:

try {
  await session.respond({ text: "…", attachments: [{ path: "/tmp/a.png" }] });
} catch (err) {
  if (err instanceof PromptAttachmentError) {
    err.reason; // "unsupported-sdk" | "unsupported-os" | "unknown"
  }
}

Rebuilding on an Xcode that ships the macOS 27 SDK enables them with no code change. Plain string prompts are unaffected.

respondWithSchema()

Generate structured output matching a GenerationSchema.

respondWithSchema(prompt: string | PromptInput, schema: GenerationSchema, options?: {
  options?: GenerationOptions
}): Promise<GeneratedContent>

Returns a GeneratedContent with typed property access.

respondWithJsonSchema()

Generate structured output from a JSON Schema object.

respondWithJsonSchema(prompt: string | PromptInput, schema: object, options?: {
  options?: GenerationOptions
}): Promise<GeneratedContent>

Returns a GeneratedContent with toObject() for the full result.

streamResponse()

Stream a response token-by-token.

streamResponse(prompt: string | PromptInput, options?: {
  options?: GenerationOptions
}): AsyncIterable<string>

Each yielded string contains only the new tokens since the last iteration.

prewarm()

Preload model resources and optionally cache a prompt prefix to reduce first-response latency. Fire-and-forget — the prewarm runs in the background on the native side.

prewarm(promptPrefix?: string): void

Parameter	Default	Description
promptPrefix	undefined	Text the model should expect at the start of the first prompt

const session = new LanguageModelSession({ instructions: "You are a helpful assistant." });
session.prewarm("Translate the following");
// ... later, the first respond() call will be faster

cancel()

Cancel an in-progress request. Advisory — the response may complete before cancellation takes effect.

cancel(): void

dispose()

Release session resources. Access transcript before calling this. Safe to call multiple times.

dispose(): void

After disposal:

• respond(), respondWithSchema(), respondWithJsonSchema(), and streamResponse() throw FoundationModelsError
• prewarm(), cancel(), and isResponding are silent no-ops

Also supports Symbol.dispose for use with TC39 Explicit Resource Management:

using session = new LanguageModelSession();
const reply = await session.respond("Hello");
// session is released when the block exits

Properties

isResponding

readonly isResponding: boolean

true while a generation request is in progress.

transcript

readonly transcript: Transcript

The session's conversation history. See Transcript.

Static Methods

fromTranscript()

Create a new session from a saved transcript.

static fromTranscript(transcript: Transcript, options?: {
  instructions?: string;
  model?: SystemLanguageModel;
  tools?: Tool[];
}): LanguageModelSession