> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
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

<ParamField path="id" type="SessionId" required>
  Unique session identifier (e.g. `"my-app-3"`, `"backend-12"`). Used for all session operations.
</ParamField>

<ParamField path="projectId" type="string" required>
  Which project this session belongs to. References a project ID from the orchestrator config.
</ParamField>

<ParamField path="status" type="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)
</ParamField>

<ParamField path="activity" type="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)
</ParamField>

<ParamField path="branch" type="string | null" required>
  Git branch name for this session. Null if branch not yet created.
</ParamField>

<ParamField path="issueId" type="string | null" required>
  Issue identifier if working on a specific issue (e.g. GitHub issue number, Linear issue ID). Null if not issue-based.
</ParamField>

<ParamField path="pr" type="PRInfo | null" required>
  Pull request information once PR is created. Null if PR not yet opened.
</ParamField>

<ParamField path="workspacePath" type="string | null" required>
  Absolute path to the workspace directory on disk. Null if workspace not yet created.
</ParamField>

<ParamField path="runtimeHandle" type="RuntimeHandle | null" required>
  Runtime handle for communicating with the session environment (tmux, docker, etc.). Null if runtime not yet initialized.
</ParamField>

<ParamField path="agentInfo" type="AgentSessionInfo | null" required>
  Agent session metadata (summary, cost estimates, internal session ID). Null if not yet available.
</ParamField>

<ParamField path="createdAt" type="Date" required>
  Timestamp when the session was created.
</ParamField>

<ParamField path="lastActivityAt" type="Date" required>
  Timestamp of last detected activity. Updated by lifecycle manager during activity checks.
</ParamField>

<ParamField path="restoredAt" type="Date">
  When this session was last restored from a terminal state. Undefined if never restored.
</ParamField>

<ParamField path="metadata" type="Record<string, string>" required>
  Key-value pairs for arbitrary metadata. Used for custom tags, labels, or plugin-specific data.
</ParamField>

## Related Types

### SessionId

```typescript theme={null}
export type SessionId = string;
```

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

### SessionStatus

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
// 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:

```typescript theme={null}
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):

```typescript theme={null}
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](/api/runtime) - Runtime execution environment interface
* [Agent](/api/agent) - Agent plugin interface for activity detection
* [Workspace](/api/workspace) - Workspace isolation interface
* [SCM](/api/scm) - Source control and PR lifecycle interface


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.