> Source: https://clickhouse.github.io/loom/pt-BR/reference/operations/session/ (Markdown: https://clickhouse.github.io/loom/pt-BR/reference/operations/session.md)

<!-- i18n: source=docs/reference/operations/session.md blob=ef3c231b70d1fcd6e901f42238a70972ed7ee390 model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em inglês](https://clickhouse.github.io/loom/reference/operations/session/), que prevalece.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/session/), which is authoritative.

<a id="session-operations"></a>

# Operações de `session`

Os campos exatos que cada operação `session.*` recebe e retorna.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Toda op é `POST /v1/<op>` via HTTP e a ferramenta MCP `loom_<op>`. Os campos de identidade (`org`, `namespace`, `agent`, `user_id`, `session_id`) são preenchidos a partir do token e da sessão MCP quando o transporte consegue fazer isso; em uma chamada HTTP sem token em um servidor de usuário único, a org da instalação é usada em todas as ops, exceto `code.*` e `tracker.*` (que mantêm a do seu plano), e em [algumas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request) também o namespace e o agente; veja [identidades e namespaces](https://clickhouse.github.io/loom/pt-BR/concepts/identities-and-namespaces/). O [índice de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica role, kind e a listagem `all` do MCP. Campos de entrada desconhecidos são atendidos e listados em `ignored_args`.

<!-- prettier-ignore-start -->

<a id="sessionbrief_delete"></a>

## `session.brief_delete`

Exclui um resumo de sessão pelo brief_key quando o usuário pede que ele seja esquecido.

`POST /v1/session.brief_delete` · MCP `loom_session_brief_delete` · role `writer` · idempotente · auditada · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | obrigatório | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente quando a op permite. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `run_id` | `str` | `'-'` | A execução do agente (escopo de tarefa) a que a chamada pertence; `'-'` para nenhuma. |
| `brief_key` | `str` | obrigatório | O resumo a excluir, como session.brief_list o mostra. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `deleted` | `bool` | False quando nenhum resumo ativo tem essa chave (desconhecido ou já excluído). |
| `brief_key` | `str` | Eco do `brief_key` de entrada. |
| `revision` | `int` | A revisão em que o resumo estava quando foi excluído; 0 quando nada foi excluído. |

<a id="sessionbrief_get"></a>

## `session.brief_get`

Carrega um brief: por `brief_key`; senão, o brief mais recente que uma determinada sessão escreveu (`from_session`); senão, o mais recente de `project`.

`POST /v1/session.brief_get` · MCP `loom_session_brief_get` · role `viewer` · leitura · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou escreve. |
| `agent` | `str` | obrigatório | O agente que escreve ou lê; `'-'` ou `'*'` significa qualquer agente, onde a op permitir. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `run_id` | `str` | `'-'` | A execução do agente (escopo da tarefa) a que a chamada pertence; `'-'` para nenhuma. |
| `brief_key` | `str` | `''` | O brief a carregar; tem precedência sobre `from_session` e `project`. |
| `from_session` | `str` | `''` | Carrega o brief mais recente para o qual este id de sessão contribuiu. |
| `project` | `str` | `''` | Carrega o brief mais recente deste projeto (usado quando `brief_key` e `from_session` estão vazios). |
| `revision` | `int` | `0` | 0 = a revisão atual; N = essa revisão do histórico. |
| `include_sections` | `bool` | `False` | Retorna também as `sections` estruturadas; False retorna apenas `rendered`. |
| `full` | `bool` | `False` | Anexa, literalmente, abaixo do brief o resumo do próprio cliente da última compactação (até ~15k caracteres a mais). |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `found` | `bool` | False quando nenhum brief correspondeu, o brief foi excluído ou a revisão não está no histórico dele. |
| `brief_key` | `str` | Chave do brief que correspondeu. |
| `revision` | `int` | A revisão retornada (a atual, a menos que `revision` tenha sido solicitada). |
| `rendered` | `str` | O brief como texto, com o resumo de compactação do cliente anexado quando `full`. |
| `sections` | `BriefSections \| None` | O brief estruturado; None, a menos que `include_sections` tenha sido definido. |
| `project` | `str` | Projeto armazenado no brief. |
| `branch` | `str` | Branch armazenada no brief. |
| `head_sha` | `str` | Commit em que o checkout estava quando esta revisão foi salva. |
| `author` | `str` | Quem escreveu a revisão: `llm`, `deterministic` ou `model` (o agente chamador). |
| `trigger` | `str` | O que motivou o salvamento da revisão (`precompact`, `session_end`, `stop`, `manual` ou `model`). |
| `actor` | `str` | O principal que salvou a revisão (`human:<subject>` / `process:<subject>`): um escritor de todo o namespace pode salvar no brief `~<user>~` de um usuário. |
| `source_sessions` | `list[str]` | Ids das sessões que contribuíram para o brief, da mais antiga para a mais recente (as últimas 20). |
| `updated_at` | `datetime \| None` | Quando a revisão retornada foi salva. |
| `age_seconds` | `int` | Segundos desde `updated_at`. |
| `revisions` | `int` | Quantas revisões o histórico do brief contém. |
| `events_total` | `int` | Eventos condensados no brief ao longo de toda a sua vida. |
| `source_chars` | `int` | Caracteres de texto de eventos condensados no brief ao longo de toda a sua vida. |
| `brief_chars` | `int` | Tamanho de `rendered` como armazenado, em caracteres. |
| `deleted` | `bool` | True quando o brief foi excluído pelo seu escritor; nada mais é servido nesse caso. |

<a id="sessionbrief_list"></a>

## `session.brief_list`

Lista os briefs de sessão neste namespace, do mais recente para o mais antigo: chave, revisão, idade, agente e objetivo, uma linha para cada.

`POST /v1/session.brief_list` · MCP `loom_session_brief_list` · papel `viewer` · leitura · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | obrigatório | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, onde a op permitir. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `run_id` | `str` | `'-'` | A execução do agente (escopo da tarefa) a que a chamada pertence; `'-'` para nenhuma. |
| `project` | `str` | `''` | Apenas briefs deste projeto; vazio = todos os projetos. |
| `mine_only` | `bool` | `False` | True = apenas os briefs do agente que chama; por padrão, os de todos os agentes. |
| `from_session` | `str` | `''` | Apenas briefs para os quais este id de sessão contribuiu; vazio = sem filtro de sessão. |
| `limit` | `int` | `10` | No máximo esta quantidade de briefs (1-50). |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `briefs` | `list[SessionBriefSummary]` | Briefs ativos, do salvo mais recentemente ao mais antigo; vazio quando o namespace não tem nenhum. |
| `rendered` | `str` | Uma linha por brief, pronta para exibir. |

<a id="sessionbrief_save"></a>

## `session.brief_save`

Revisa (ou inicia) um brief.

`POST /v1/session.brief_save` · MCP `loom_session_brief_save` · função `writer` · idempotente · auditado · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | obrigatório | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente quando a op permite. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `run_id` | `str` | `'-'` | A execução do agente (escopo da tarefa) a que a chamada pertence; `'-'` para nenhuma. |
| `brief_key` | `str` | `''` | O endereço do brief no namespace. |
| `project` | `str` | `''` | Projeto ao qual o trabalho pertence; junto com `branch` forma a chave automática. |
| `repo` | `str` | `''` | Repositório em que o trabalho está, armazenado no brief; vazio mantém o valor armazenado. |
| `branch` | `str` | `''` | Branch em que o trabalho está; junto com `project` forma a chave automática. |
| `head_sha` | `str` | `''` | Commit em que o checkout estava ao salvar; vazio mantém o valor armazenado. |
| `trigger` | `Literal['precompact', 'session_end', 'stop', 'manual', 'model']` | `'manual'` | O que motivou o salvamento: `manual` e `model` sempre salvam; os automáticos `precompact`, `session_end` e `stop` não armazenam nada enquanto a gravação do namespace estiver desligada. |
| `events` | `list[BriefEvent]` | *(calculado)* | O que aconteceu desde o último salvamento (no máximo 4000 eventos), condensado na revisão. |
| `sections` | `BriefSections \| None` | `None` | Um brief que o agente chamador escreveu a partir do próprio contexto: as seções preenchidas substituem as armazenadas (decisões e becos sem saída são acrescentados). |
| `event_cursor` | `str` | `''` | Posição opaca do cliente em que os eventos terminam (um índice de linha da transcrição). |
| `if_revision` | `int \| None` | `None` | Compare-and-set: recusa (409) a menos que a revisão armazenada seja esta. |
| `use_llm` | `bool \| None` | `None` | Força o construtor determinístico (False) ou o modelo (True); None = a configuração da implantação. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `brief_key` | `str` | A chave sob a qual o brief foi salvo (a chave automática resolvida quando nenhuma foi informada). |
| `revision` | `int` | A revisão do brief após esta chamada (a armazenada quando não houve mudança; 0 quando não há nenhuma ativa). |
| `changed` | `bool` | True quando uma nova revisão foi gravada; False quando `reason` explica o motivo. |
| `author` | `str` | "llm" (revisado pelo modelo), "deterministic" (nenhum modelo configurado, ou ele falhou; nunca sob a política de extração de um operador), "model" (o agente chamador escreveu as seções). |
| `reason` | `str` | Por que nada foi gravado: `nothing-to-save`, `recording_off`, `already-saved` ou `not-revised` (há uma política de extração de um operador em vigor e não há modelo para revisar o brief); vazio quando `changed`. |
| `rendered` | `str` | O brief como texto, pronto para exibir; o armazenado quando nada mudou. |
| `stats` | `SessionBriefStats` | Contagens deste salvamento: eventos, janelas, tamanhos, tokens e o modelo usado. |

<!-- prettier-ignore-end -->
