Interface: App<P>

Defined in: core/src/app/types.ts:2078

A reusable app instance created by createApp().

All sessions are persistent sessions internally. Ephemeral execution (run/stream) creates a session, sends once, then closes immediately.

Example

typescript

const MyAgent = ({ query, context }) => (
  <>
    <System>You are helpful. {context}</System>
    <Timeline />
    <User>{query}</User>
  </>
);

const app = createApp(MyAgent, { model });

// Ephemeral: create → send → close
const result = await app.run({ query: "Hello!", context: "Be concise" });

// Streaming ephemeral
for await (const event of app.stream({ query: "Hello!" })) {
  console.log(event);
}

// Persistent session (new with generated ID)
const session = app.session();
await session.render({ query: "Hello!" });
await session.render({ query: "Follow up" });
await session.close();

// Named session (get-or-create by ID)
const conv = app.session('conv-123');
await conv.render({ query: "Hello!" });

// Session with options
const withOpts = app.session({ sessionId: 'conv-456', maxTicks: 5 });

Type Parameters

P

P = { }

Properties

run

run: Procedure<(input) => SessionExecutionHandle, true>

Defined in: core/src/app/types.ts:2139

Run the app with input.

Returns SessionExecutionHandle (AsyncIterable, not PromiseLike):

await handle.result → SendResult
for await (const event of handle) → StreamEvent

Creates an ephemeral session internally (create → run → close).

Examples

typescript

const result = await app.run({
  props: { system: "You are helpful" },
  messages: [{ role: "user", content: [{ type: "text", text: "Hello!" }] }],
}).result;
console.log(result.response);

typescript

const result = await app.run({
  props: { system: "You are helpful" },
  messages: [{ role: "user", content: [{ type: "text", text: "Follow up" }] }],
  history: previousConversation.entries,
  maxTicks: 5,
  devTools: true,
}).result;

typescript

const handle = await app.run({ messages });
handle.queueMessage({ role: "user", content: [...] });
const result = await handle.result;

sessions

readonly sessions: readonly string[]

Defined in: core/src/app/types.ts:2183

List active session IDs.

skills

readonly skills: SkillRegistry

Defined in: core/src/app/types.ts:2101

App-level skill registry — discovery and retrieval surface for the skills available across sessions of this app.

Skills registered here are:

Resolvable by name from session.skill(name, { args })
Exposed to the model via the implicit skill tool (when the registry is non-empty, the tool is auto-added to sessions and its description dynamically lists available skills)

Example

typescript

const Triage = await loadSkill("./skills/triage");
app.skills.register(Triage);

// Or load a whole directory of skills
await app.skills.loadDir("./skills");

// Search by metadata or text
const found = app.skills.search({ query: "issue", metadata: { author: "x" } });

Methods

close()

close(sessionId): Promise<void>

Defined in: core/src/app/types.ts:2178

Close and cleanup a session.

Parameters

sessionId

string

Returns

Promise<void>

getSession()

getSession(sessionId): Session<P> | undefined

Defined in: core/src/app/types.ts:2196

Get a live session by ID. Returns undefined if not in memory.

Unlike session(id) which creates-or-gets, this is read-only inspection. Does not hydrate from store or create a new session.

Parameters

sessionId

string

Returns

Session<P> | undefined

has()

has(sessionId): boolean

Defined in: core/src/app/types.ts:2188

Check if a session exists (in memory).

Parameters

sessionId

string

Returns

boolean

onSessionClose()

onSessionClose(handler): () => void

Defined in: core/src/app/types.ts:2206

Parameters

handler

(sessionId) => void

Returns

(): void

Returns

void

onSessionCreate()

onSessionCreate(handler): () => void

Defined in: core/src/app/types.ts:2201

Parameters

handler

(session) => void

Returns

(): void

Returns

void

processInbox()

processInbox(): Promise<void>

Defined in: core/src/app/types.ts:2231

Process all pending inbox messages across all sessions.

Hydrates sessions as needed (from store) and drains their inboxes. Call this at startup to sweep durable backends after restart.

Returns

Promise<void>

receive()

Call Signature

receive(message): Promise<void>

Defined in: core/src/app/types.ts:2215

Deliver a message to the inbox with routing.

Routes via sessionResolver if configured, otherwise creates a new session. The message is written to the inbox storage; if the target session is active, its subscriber fires immediately and drains.

Parameters

message

InboxMessageInput

Returns

Promise<void>

Call Signature

receive(sessionId, message): Promise<void>

Defined in: core/src/app/types.ts:2223

Deliver a message directly to a specific session's inbox by ID.

Bypasses the sessionResolver entirely — writes straight to inbox storage. Use this for session-to-session communication where the target is already known.

Parameters

sessionId

string

message

InboxMessageInput

Returns

Promise<void>

send()

send(input, options?): Promise<SessionExecutionHandle>

Defined in: core/src/app/types.ts:2147

Send to a session.

Without sessionId: creates ephemeral session, executes, destroys. With sessionId: creates or reuses managed session (may hydrate from store).

Parameters

input

SendInput<P>

options?

sessionId?

string

Returns

Promise<SessionExecutionHandle>

session()

Call Signature

session(id?): Promise<Session<P>>

Defined in: core/src/app/types.ts:2172

Get or create a session.

This is the primary way to access sessions:

session() - Creates new session with generated ID
session('id') - Gets existing or creates new session with that ID
session({ sessionId, ...opts }) - Gets or creates with options

Use app.has(id) to check if a session exists without creating it.

Parameters

id?

string

Returns

Promise<Session<P>>

Example

typescript

// New session with generated ID
const session = app.session();

// Get or create by ID
const conv = app.session('conv-123');

// With options
const withOpts = await app.session({ sessionId: 'conv-456', maxTicks: 5 });
const newWithOpts = await app.session({ maxTicks: 5 }); // Generated ID

Call Signature

session(options): Promise<Session<P>>

Defined in: core/src/app/types.ts:2173

Parameters

options

SessionOptions

Returns

Promise<Session<P>>

knob

Functions