Operações de `session`
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Os campos exatos que cada operação session.* recebe e retorna.
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 também o namespace e o agente; veja identidades e namespaces. O índice de operações explica role, kind e a listagem all do MCP. Campos de entrada desconhecidos são atendidos e listados em ignored_args.
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. |
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. |
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. |
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. |