# SessionService

> The SessionService methods and their request and response messages.

Source: https://engramsfactory.com/docs/api/session/

Generated from [`session.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/session.proto). Every method is
`POST /rpc/engram.app.v1.SessionService/<Method>` with a JSON or protobuf body and an
`x-api-key` header.

## Methods

| Method | Request | Response |
|---|---|---|
| `ListSessions` | [`ListSessionsRequest`](#listsessionsrequest) | [`ListSessionsResponse`](#listsessionsresponse) |
| `CreateSession` | [`CreateSessionRequest`](#createsessionrequest) | [`CreateSessionResponse`](#createsessionresponse) |
| `GetSession` | [`GetSessionRequest`](#getsessionrequest) | [`GetSessionResponse`](#getsessionresponse) |
| `DeleteSession` | [`DeleteSessionRequest`](#deletesessionrequest) | [`DeleteSessionResponse`](#deletesessionresponse) |
| `SendPrompt` | [`SendPromptRequest`](#sendpromptrequest) | [`SendPromptResponse`](#sendpromptresponse) |
| `Interrupt` | [`InterruptRequest`](#interruptrequest) | [`InterruptResponse`](#interruptresponse) |
| `EditQueuedPrompt` | [`EditQueuedPromptRequest`](#editqueuedpromptrequest) | [`EditQueuedPromptResponse`](#editqueuedpromptresponse) |
| `DequeueQueuedPrompt` | [`DequeueQueuedPromptRequest`](#dequeuequeuedpromptrequest) | [`DequeueQueuedPromptResponse`](#dequeuequeuedpromptresponse) |
| `CompleteToolCall` | [`CompleteToolCallRequest`](#completetoolcallrequest) | [`CompleteToolCallResponse`](#completetoolcallresponse) |
| `StreamEvents` | [`StreamEventsRequest`](#streameventsrequest) | [`SessionEvent`](#sessionevent) (stream) |
| `ListSessionEvents` | [`ListSessionEventsRequest`](#listsessioneventsrequest) | [`ListSessionEventsResponse`](#listsessioneventsresponse) |
| `Exec` | [`ExecRequest`](#execrequest) | [`ExecOutput`](#execoutput) (stream) |
| `CancelExec` | [`CancelExecRequest`](#cancelexecrequest) | [`CancelExecResponse`](#cancelexecresponse) |
| `WriteFile` | [`WriteFileRequest`](#writefilerequest) (stream) | [`WriteFileResponse`](#writefileresponse) |
| `ReadFile` | [`ReadFileRequest`](#readfilerequest) | [`ReadFileResponse`](#readfileresponse) (stream) |
| `CopyFiles` | [`CopyFilesRequest`](#copyfilesrequest) | [`CopyFilesResponse`](#copyfilesresponse) |
| `GetLog` | [`GetLogRequest`](#getlogrequest) | [`GetLogResponse`](#getlogresponse) |
| `Snapshot` | [`SnapshotRequest`](#snapshotrequest) | [`SnapshotResponse`](#snapshotresponse) |
| `EnsureBrowser` | [`EnsureBrowserRequest`](#ensurebrowserrequest) | [`EnsureBrowserResponse`](#ensurebrowserresponse) |
| `EnsureIde` | [`EnsureIdeRequest`](#ensureiderequest) | [`EnsureIdeResponse`](#ensureideresponse) |
| `Resume` | [`ResumeRequest`](#resumerequest) | [`ResumeResponse`](#resumeresponse) |
| `EvictLocal` | [`EvictLocalRequest`](#evictlocalrequest) | [`EvictLocalResponse`](#evictlocalresponse) |
| `EvictIdle` | [`EvictIdleRequest`](#evictidlerequest) | [`EvictIdleResponse`](#evictidleresponse) |
| `ListCheckpoints` | [`ListCheckpointsRequest`](#listcheckpointsrequest) | [`ListCheckpointsResponse`](#listcheckpointsresponse) |
| `GetArtifact` | [`GetArtifactRequest`](#getartifactrequest) | [`GetArtifactResponse`](#getartifactresponse) (stream) |
| `CreateArtifactFromPath` | [`CreateArtifactFromPathRequest`](#createartifactfrompathrequest) | [`CreateArtifactFromPathResponse`](#createartifactfrompathresponse) |

## Messages

### AppEndpoint

| Field | Type |
|---|---|
| `hostname` | `string` |
| `port` | `uint32` |

### ArtifactMetadata

| Field | Type |
|---|---|
| `media_type` | `string` |
| `size_bytes` | `uint64` |
| `file_name` | `string` |

### CancelExecRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `exec_id` | `string` |

### CancelExecResponse

No fields.

### CheckpointSummary

| Field | Type |
|---|---|
| `snapshot_id` | `string` |
| `created_at` | `string` |
| `size_bytes` | `uint64` |
| `events_cursor` | `int64` (optional) |
| `recoverable` | `bool` |
| `is_latest` | `bool` |

### CompleteToolCallRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `tool_call_id` | `string` |
| `result_json` | `string` |

### CompleteToolCallResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `note` | `string` |

### ConversationEntry

| Field | Type |
|---|---|
| `idx` | `int64` |
| `kind` | `string` |
| `at` | `string` |
| `payload_json` | `string` |

### CopyFileResult

| Field | Type |
|---|---|
| `path` | `string` |
| `size_bytes` | `uint64` |
| `sha256` | `string` |

### CopyFilesRequest

| Field | Type |
|---|---|
| `source_session_id` | `string` |
| `target_session_id` | `string` |
| `paths` | repeated `string` |

### CopyFilesResponse

| Field | Type |
|---|---|
| `files` | repeated [`CopyFileResult`](#copyfileresult) |

### CreateArtifactFromPathRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `path` | `string` |
| `caption` | `string` (optional) |
| `suppress_event` | `bool` |

### CreateArtifactFromPathResponse

| Field | Type |
|---|---|
| `artifact_id` | `string` |
| `media_type` | `string` |
| `size_bytes` | `uint64` |

### CreateSessionRequest

| Field | Type |
|---|---|
| `image_uri` | `string` |
| `mode` | `string` |
| `prompt` | `string` (optional) |
| `prompt_id` | `string` (optional) |
| `secrets` | `map<string, string>` |
| `harness_env` | `map<string, string>` |
| `selected_skills` | repeated `string` |
| `capabilities` | repeated `string` |
| `integration_policy_json` | `string` |
| `harness` | `string` (optional) |
| `oauth_credential` | [`OAuthCredentialBinding`](#oauthcredentialbinding) |
| `harness_mode` | `string` (optional) |
| `requested_session_id` | `string` (optional) |
| `apps` | repeated [`AppEndpoint`](#appendpoint) |

### CreateSessionResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `status` | `string` |
| `image_version` | `string` |
| `kind` | `string` |

### DeleteSessionRequest

| Field | Type |
|---|---|
| `session_id` | `string` |

### DeleteSessionResponse

No fields.

### DequeueQueuedPromptRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `prompt_id` | `string` |

### DequeueQueuedPromptResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `note` | `string` |

### EditQueuedPromptRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `prompt_id` | `string` |
| `text` | `string` |

### EditQueuedPromptResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `note` | `string` |

### EnsureBrowserRequest

| Field | Type |
|---|---|
| `session_id` | `string` |

### EnsureBrowserResponse

| Field | Type |
|---|---|
| `port` | `uint32` |

### EnsureIdeRequest

| Field | Type |
|---|---|
| `session_id` | `string` |

### EnsureIdeResponse

| Field | Type |
|---|---|
| `port` | `uint32` |

### EvictIdleRequest

| Field | Type |
|---|---|
| `session_id` | `string` |

### EvictIdleResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `status` | `string` |

### EvictLocalRequest

| Field | Type |
|---|---|
| `session_id` | `string` |

### EvictLocalResponse

No fields.

### ExecExit

| Field | Type |
|---|---|
| `exit_status` | `int32` (optional) |
| `rusage` | [`ExecRusage`](#execrusage) |

### ExecOutput

| Field | Type |
|---|---|
| `started` | [`ExecStarted`](#execstarted) (one of event) |
| `stdout` | `bytes` (one of event) |
| `stderr` | `bytes` (one of event) |
| `exit` | [`ExecExit`](#execexit) (one of event) |

### ExecRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `command` | `string` (optional) |
| `argv` | repeated `string` |
| `env` | `map<string, string>` |
| `workdir` | `string` (optional) |
| `timeout_secs` | `uint64` (optional) |
| `exec_id` | `string` (optional) |
| `stdout_offset` | `uint64` (optional) |
| `stderr_offset` | `uint64` (optional) |
| `wake` | `bool` (optional) |

### ExecRusage

| Field | Type |
|---|---|
| `wall_ms` | `uint64` |
| `peak_rss_kb` | `uint64` (optional) |
| `user_cpu_ms` | `uint64` (optional) |
| `sys_cpu_ms` | `uint64` (optional) |

### ExecStarted

| Field | Type |
|---|---|
| `exec_id` | `string` |

### GetArtifactRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `artifact_id` | `string` |

### GetArtifactResponse

| Field | Type |
|---|---|
| `metadata` | [`ArtifactMetadata`](#artifactmetadata) (one of msg) |
| `chunk` | `bytes` (one of msg) |

### GetLogRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `kind` | `string` (optional) |
| `limit` | `int64` (optional) |
| `tail` | `bool` (optional) |

### GetLogResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `kind` | `string` |
| `events` | repeated [`ConversationEntry`](#conversationentry) |

### GetSessionRequest

| Field | Type |
|---|---|
| `session_id` | `string` |

### GetSessionResponse

| Field | Type |
|---|---|
| `session` | [`Session`](#session) |

### InterruptRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `source` | `string` |

### InterruptResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `note` | `string` |

### ListCheckpointsRequest

| Field | Type |
|---|---|
| `session_id` | `string` |

### ListCheckpointsResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `checkpoints` | repeated [`CheckpointSummary`](#checkpointsummary) |

### ListSessionEventsRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `after_idx` | `int64` (optional) |
| `limit` | `int64` (optional) |
| `before_idx` | `int64` (optional) |
| `kinds` | repeated `string` |
| `tool_names` | repeated `string` |

### ListSessionEventsResponse

| Field | Type |
|---|---|
| `events` | repeated [`SessionEvent`](#sessionevent) |
| `next_after_idx` | `int64` |

### ListSessionsRequest

No fields.

### ListSessionsResponse

| Field | Type |
|---|---|
| `sessions` | repeated [`SessionListItem`](#sessionlistitem) |

### OAuthCredentialBinding

| Field | Type |
|---|---|
| `subject` | `OAuthSubject` |
| `provider` | `string` |

### ReadFileMetadata

| Field | Type |
|---|---|
| `path` | `string` |
| `size_bytes` | `uint64` |
| `sha256` | `string` |
| `file_name` | `string` |

### ReadFileRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `path` | `string` |

### ReadFileResponse

| Field | Type |
|---|---|
| `metadata` | [`ReadFileMetadata`](#readfilemetadata) (one of frame) |
| `chunk` | `bytes` (one of frame) |

### ResumeRequest

| Field | Type |
|---|---|
| `session_id` | `string` |

### ResumeResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `snapshot_id` | `string` (optional) |
| `size_bytes` | `uint64` (optional) |
| `note` | `string` |

### SendPromptRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `text` | `string` |
| `prompt_id` | `string` |
| `harness_mode` | `string` (optional) |

### SendPromptResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `note` | `string` |

### Session

| Field | Type |
|---|---|
| `id` | `string` |
| `status` | `string` |
| `host_id` | `string` (optional) |
| `sandbox_id` | `string` (optional) |
| `image` | `string` |
| `mode` | `string` |
| `created_at` | `string` |
| `last_active_at` | `string` |
| `suggested_title` | `string` (optional) |
| `last_event_at` | `string` (optional) |

### SessionEvent

| Field | Type |
|---|---|
| `idx` | `int64` (optional) |
| `kind` | `string` |
| `payload_json` | `string` |

### SessionListItem

| Field | Type |
|---|---|
| `session` | [`Session`](#session) |
| `owner_email` | `string` (optional) |
| `owner_name` | `string` (optional) |
| `owner_kind` | `string` (optional) |

### SnapshotRequest

| Field | Type |
|---|---|
| `session_id` | `string` |

### SnapshotResponse

| Field | Type |
|---|---|
| `session_id` | `string` |
| `snapshot_id` | `string` (optional) |
| `size_bytes` | `uint64` (optional) |
| `note` | `string` |

### StreamEventsRequest

| Field | Type |
|---|---|
| `session_id` | `string` |
| `since` | `int64` (optional) |
| `durable_only` | `bool` |

### WriteFileMetadata

| Field | Type |
|---|---|
| `session_id` | `string` |
| `path` | `string` |
| `size_bytes` | `uint64` |
| `sha256` | `string` |
| `mode` | `uint32` (optional) |

### WriteFileRequest

| Field | Type |
|---|---|
| `metadata` | [`WriteFileMetadata`](#writefilemetadata) (one of frame) |
| `chunk` | `bytes` (one of frame) |

### WriteFileResponse

| Field | Type |
|---|---|
| `path` | `string` |
| `size_bytes` | `uint64` |
| `sha256` | `string` |
