Skip to content
Justack

Sessions

Sessions are communication channels between your AI agent and human recipients, backed by real-time WebSocket connections. For method details, see the TypeScript SDK reference.

Lifecycle

  1. Create — client.sessions.create() opens a WebSocket and returns a Session object
  2. Interact — session.log() sends updates, session.ask() blocks for human input
  3. Close — session.close() cleans up the WebSocket connection
  4. Resume — client.sessions.resume(id) reconnects to an existing session
  5. Expire — Session data is deleted after the retention period (default: 1 month, up to 12 on Pro)

Session data persists until expiry. Closing only disconnects the WebSocket — you can resume later.

Log vs Ask

Log is fire-and-forget. Use it for progress updates:

await session.log("Processing step 1 of 3...");
await session.log("Scanning files...", { persist: false }); // ephemeral

Ask blocks until a recipient responds. Requires at least one recipient:

const { approved } = await session.ask("Deploy?", {
  inputs: [{ type: "confirm", name: "approved" }] as const,
});

Typed Inputs

ask() supports three input types. Use as const to get inferred response types:

TypeResponse TypeUse Case
textstringFree-form input
confirmbooleanYes/no decisions
selectstring or string[]Choose from options

Combine multiple inputs in a single ask. See Input Types for all options.

Markdown Support

Message content supports GitHub-flavored Markdown:

await session.ask(
  `## Summary\n| File | Changes |\n|------|--------|\n| index.ts | +50 |`,
  { inputs: [{ type: "confirm", name: "approved" }] as const }
);

Timeout Handling

ask() times out after 5 minutes by default. Customize with the timeout option:

import { TimeoutError } from "@justack/sdk";


try {
  const response = await session.ask("Approve?", {
    inputs: [{ type: "confirm", name: "ok" }] as const,
    timeout: 60000, // 1 minute
  });
} catch (error) {
  if (error instanceof TimeoutError) {
    // handle timeout
  }
}

Next Steps