Session

Core session interface representing a running agent session with lifecycle state, activity tracking, and metadata

Overview

The Session interface represents a running agent session in the orchestrator. Each session encapsulates an AI coding agent working on a specific task, tracking its lifecycle state, activity, workspace, and associated resources.

Interface Definition

export interface Session {
  id: SessionId;
  projectId: string;
  status: SessionStatus;
  activity: ActivityState | null;
  branch: string | null;
  issueId: string | null;
  pr: PRInfo | null;
  workspacePath: string | null;
  runtimeHandle: RuntimeHandle | null;
  agentInfo: AgentSessionInfo | null;
  createdAt: Date;
  lastActivityAt: Date;
  restoredAt?: Date;
  metadata: Record<string, string>;
}

Properties

id · SessionId · required

Unique session identifier (e.g. "my-app-3", "backend-12"). Used for all session operations.

projectId · string · required

Which project this session belongs to. References a project ID from the orchestrator config.

status · SessionStatus · required

Current lifecycle status of the session. One of:

• "spawning" - Session is being created
• "working" - Agent is actively working
• "pr_open" - PR has been created
• "ci_failed" - CI checks failed
• "review_pending" - Awaiting code review
• "changes_requested" - Reviewer requested changes
• "approved" - PR approved
• "mergeable" - Ready to merge
• "merged" - PR merged (terminal state)
• "cleanup" - Cleaning up resources (terminal state)
• "needs_input" - Waiting for human input
• "stuck" - Agent is stuck/blocked
• "errored" - Session encountered an error (terminal state)
• "killed" - Session was manually killed (terminal state)
• "done" - Session completed successfully (terminal state)
• "terminated" - Session terminated (terminal state)

activity · ActivityState | null · required

Activity state from agent plugin (null = not yet determined). One of:

• "active" - Agent is processing (thinking, writing code)
• "ready" - Agent finished its turn, alive and waiting for input
• "idle" - Agent has been inactive for a while (stale)
• "waiting_input" - Agent is asking a question / permission prompt
• "blocked" - Agent hit an error or is stuck
• "exited" - Agent process is no longer running (terminal state)

branch · string | null · required

Git branch name for this session. Null if branch not yet created.

issueId · string | null · required

Issue identifier if working on a specific issue (e.g. GitHub issue number, Linear issue ID). Null if not issue-based.

pr · PRInfo | null · required

Pull request information once PR is created. Null if PR not yet opened.

workspacePath · string | null · required

Absolute path to the workspace directory on disk. Null if workspace not yet created.

runtimeHandle · RuntimeHandle | null · required

Runtime handle for communicating with the session environment (tmux, docker, etc.). Null if runtime not yet initialized.

agentInfo · AgentSessionInfo | null · required

Agent session metadata (summary, cost estimates, internal session ID). Null if not yet available.

createdAt · Date · required

Timestamp when the session was created.

lastActivityAt · Date · required

Timestamp of last detected activity. Updated by lifecycle manager during activity checks.

restoredAt · Date

When this session was last restored from a terminal state. Undefined if never restored.

metadata · Record<string, string> · required

Key-value pairs for arbitrary metadata. Used for custom tags, labels, or plugin-specific data.

Related Types

SessionId

export type SessionId = string;

Unique session identifier string (e.g. "my-app-1", "backend-12").

SessionStatus

export type SessionStatus =
  | "spawning" | "working" | "pr_open" | "ci_failed"
  | "review_pending" | "changes_requested" | "approved"
  | "mergeable" | "merged" | "cleanup" | "needs_input"
  | "stuck" | "errored" | "killed" | "done" | "terminated";

ActivityState

export type ActivityState =
  | "active"         // agent is processing
  | "ready"          // agent finished turn, waiting for input
  | "idle"           // agent inactive for a while
  | "waiting_input"  // agent asking a question
  | "blocked"        // agent hit an error
  | "exited";        // agent process no longer running

SessionSpawnConfig

export interface SessionSpawnConfig {
  projectId: string;
  issueId?: string;
  branch?: string;
  prompt?: string;
  agent?: string;  // Override agent plugin
}

Configuration for creating a new session via SessionManager.spawn().

Usage Examples

Creating a Session

import type { SessionSpawnConfig } from "@composio/ao-core";

const config: SessionSpawnConfig = {
  projectId: "my-app",
  issueId: "#42",
  prompt: "Fix the authentication bug"
};

const session = await sessionManager.spawn(config);
console.log(`Session ${session.id} created on branch ${session.branch}`);

Checking Session State

import { isTerminalSession, TERMINAL_STATUSES } from "@composio/ao-core";

// Check if session is in terminal state
if (isTerminalSession(session)) {
  console.log("Session has finished");
}

// Check if session can be restored
if (isRestorable(session)) {
  const restored = await sessionManager.restore(session.id);
}

Monitoring Activity

// Check if agent is actively working
if (session.activity === "active") {
  console.log("Agent is processing...");
}

// Check if human input needed
if (session.activity === "waiting_input" || session.status === "needs_input") {
  await notifier.notify({
    type: "session.needs_input",
    sessionId: session.id,
    message: "Session waiting for your input"
  });
}

Implementation Notes

Terminal States

Sessions in terminal states (defined by TERMINAL_STATUSES and TERMINAL_ACTIVITIES) have finished executing and their resources can be cleaned up:

export const TERMINAL_STATUSES: ReadonlySet<SessionStatus> = new Set([
  "killed", "terminated", "done", "cleanup", "errored", "merged"
]);

export const TERMINAL_ACTIVITIES: ReadonlySet<ActivityState> = new Set(["exited"]);

Restorable Sessions

Some terminal sessions can be restored (e.g. errored, killed) while others cannot (e.g. merged):

export const NON_RESTORABLE_STATUSES: ReadonlySet<SessionStatus> = new Set(["merged"]);

export function isRestorable(session: { status: SessionStatus; activity: ActivityState | null }): boolean {
  return isTerminalSession(session) && !NON_RESTORABLE_STATUSES.has(session.status);
}

Activity Detection

The activity field is populated by the agent plugin’s getActivityState() method, which uses agent-native mechanisms (JSONL logs, SQLite, etc.) rather than terminal output parsing.

Metadata Persistence

Session state is persisted to flat key-value files in the data directory. The metadata format is backwards-compatible with the original bash implementation.

See Also

• Runtime - Runtime execution environment interface
• Agent - Agent plugin interface for activity detection
• Workspace - Workspace isolation interface
• SCM - Source control and PR lifecycle interface