Skip to main content

​
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.

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us