GigaChat in Pulse - design
Status: implemented (Pulse 0.15.4+). The document was originally written before the advent of built-in ApiAgentSession (Local Model agent) so instead of having a separate agent loop, GigaChat reuses it - see Architecture below.
GigaChat in Pulse is now two different things, and they should not be confused:
- agent — manages the task, edits files, runs commands (the entire document, except for the section of the same name below);
- AI action provider — writes the commit message, the name stash, an explanation of the changes and PR texts (section “GigaChat as a provider of AI actions”).
They have the authorization key one — the one specified on the agent’s card.
Goal: connect GigaChat (Sber) via authorization key as another agent - next to Claude Code, Kimi Code and Codex. GigaChat does not have an ACP adapter and an agent-loop CLI, so the agent built-in: the main process itself runs the “model → tool call → result → model” loop on top of the HTTP API and turns it into the same SessionEvent, as ACP adapters. For renderer there is no difference.
API (what is known)
| What | How |
|---|---|
| Authorization | POST https://ngw.devices.sberbank.ru:9443/api/v2/oauth, headers Authorization: Basic <key>, RqUID: <uuid>, body scope=GIGACHAT_API_PERS (or _B2B / _CORP) → access_token for 30 minutes; update 3 minutes before expiration (expires_at, normalize seconds → ms) |
| Models | GET https://gigachat.devices.sberbank.ru/api/v1/models → list (GigaChat-2, GigaChat-2-Pro, GigaChat-2-Max, ...) - this is the config option “model” |
| Dialogue | POST /api/v1/chat/completions with messages, functions (JSON tool schemas), function_call: "auto", stream: true (SSE) |
| Calling a function | answer with finish_reason: "function_call" and delta.function_call {name, arguments} (entirely in one chunk, no id); the result is returned by the message role: "function" with connection by name |
| TLS | chain of certificates from the NCA of the Ministry of Digital Development; PEM of the root lies in resources/certs/russian_trusted_root_ca.pem (extraResources → <Resources>/certs/), connects via https.Agent({ ca }). rejectUnauthorized: false We don't use it. Transport - node:https (the undici package is a transitive dependency and is not included in the assembly) |
The key is the secret: keep it in userData/secrets.json with rights 0600 (values are encrypted by safeStorage), never write to the transcript, logs and agent-config.json; in the UI there is only “set / not set” and a tail. access_token is not written to the logs (and is thus masked
net.redactForLog by keys authorization/access_token).
Architecture (as implemented)
src/main/agents/
apiAgentSession.ts general loop "request → tool calls → results → request":
flavor 'openai' | 'gigachat', hooks getAuthToken/fetchImpl
apiAgentStream.ts SSE parsing: content, tool_calls (openai), function_call (gigachat), usage
apiAgentTools.ts tools read_file/write_file/edit_file/list_dir/search/bash (general)
gigachat/
client.ts OAuth with token cache (−3 min before expires_at), models(),
createGigaChatFetch() - https.Agent with CA NCA
registry.ts gigachat: available = key set; checkGigaChat() - “Check” button
- Integration with ApiAgentSession — without a chat client layer: the session receives
flavor: 'gigachat',fetchImpl: client.fetch(CA) andgetAuthToken: () => client.getToken()(the token is asked before each request, the cache is inside the client). The format differences are encapsulated in the session and apiAgentStream:- request:
functions(=TOOL_SPECS.map(t => t.function)without wrappertype) +function_call: 'auto'instead oftools;stream_optionswe do not send (not supported); - stream:
delta.function_callaccumulates in apiAgentStream along withtool_calls; - history:
assistant { content, function_call { name, arguments } }→{ role: 'function', name, content }instead oftool_calls+role: 'tool'.
- request:
- Tools, permissions (Manual/Auto), 30 lap limit, cancellation via AbortController, events
message/tool_call/tool_call_update/usage/turn_complete— common with the “Local Model”. - Config options:
model(from/modelsafter “Check” or the start of the session; before that - fallback GigaChat-2 / Pro / Max),mode(manual/auto) - the same composer chips. - Usage:
usage.{prompt_tokens,completion_tokens}from the final SSE chunk → eventusage(default window 32k, like the local model). - Scope from the card settings (
GIGACHAT_API_PERS/_B2B/_CORP, garbage → PERS) goes to OAuth.
Settings
Section “Agents” → GigaChat card: field “Authorization key” (password), select scope, button “Check” (IPC pulse:check-gigachat: OAuth + /models, shows models and token expiration, models are cached in agent-config.json as config option). Agent
available: true, when the key is specified and the agent is enabled.
GigaChat as an AI Action Provider
The Pulse AI engine is texts that are written not by an agent, but by an application on your button: commit message, stash name, explanation of changes, PR title and body; The atomic commit plan and AI conflict resolution go through the same engine. There were four providers for them - CLI agent, Anthropic, OpenAI and any OpenAI-compatible server; now on the list Settings → AI there is a fifth GigaChat (Sberbank), right after the CLI agent.
The key is not entered a second time. There is only one Sber authorization key per application, located in
secrets.json under gigachatAuthKey and is set on the agent card. Therefore, the provider
needsApiKey: false, but the truth about access is given by a separate method hasCredentials - otherwise the AI page would show a second key field that no one reads. In place of the field is the line “Authorization key”: the “key set / not set” icon, a button to go to the agent card and a button "Check".
“Verify” - a real exchange of key for token, past the live session client (fresh). The answer “working” from the cache would only mean “we still have the token,” and the token lives for half an hour: during this time the key could be revoked, and Pulse would announce to the workers what it does not know.
The access type (scope) and the list of models are taken from the same place where the agent takes them: scope - from the card, models - from its cache after “Check”, and before the first check - the well-known set GigaChat-2 / Pro / Max. The scope selected by the client is remembered in the card.
One client per session. The provider reassembles for each action (AIService.providerFor), so the transport lives separately (cacheGigaChatTransport): without this, each commit message would re-change the key to a token via OAuth, re-read from the PEM disk of the root of the Mintsifra NUC and raise a new one https.Agent, and a three-minute token cache inside the client would never work. The client survives calls until the key and scope have changed.
Failures are named differently because they are treated differently:
| What came | What does Pulse say? |
|---|---|
| OAuth 401/403, "does not match any access type" | the key is rejected - and immediately the address: “Settings → Agents → GigaChat card” |
| OAuth didn't get through | the network is unavailable (a person should not change the working key due to a connection failure) |
| chat/completions 402 | The account does not have available tokens for this model - top up the package or select a model from the tariff |
| 404 | model is not available to the account |
| 429 | too many requests, try again in a minute |
| empty answer | so it is said; not issued as text |
The card address in the error text is required: window (renderer/src/ai.ts) shows the words of the provider only if he himself named the settings section. Without an address, a person would receive the general advice “check the key in Settings → AI,” where GigaChat does not have a key field at all.
Borders
- There is no transcript of speech via GigaChat. The microphone in the composer works through the AI provider, and GigaChat does not do this: the button does not disappear and does not promise anything - the tooltip says that Pulse does not transcribe speech through GigaChat, and a solution is suggested (OpenAI or its server).
- Not a single provider offers streaming output for AI actions. Waiting for the full answer
stream: false; The GigaChat agent has a thread, but it doesn't exist here. - The rest of the token package is not shown in AI actions. The client knows how to ask
/balance, and the agent can see the remainder - with the “limit” chip in the chat after each turn and in the response of the “Check” button on the card. AI actions do not ask for it: only a 402 refusal indicates an exhausted package, that is, retroactively. - This road was not tested on the live key of Sber. All checks are on a fake server; live run (OAuth,
/chat/completions, model response) remains manual.
Tests
ai/providers/gigachat.test.ts— AI action provider: request form, default model from card, refusal without key and without models with card address, parsing 401 / 402 / 500, cancellation during OAuth, lack of PEM root,verifyKeylike real OAuth, one client for two actions in a row, “Check” past the cache, changing the key.renderer/src/aiErrors.test.ts- where the advice leads: the words of the provider with the section address are more important than the general text about “Settings → AI”.gigachat/client.test.ts— OAuth cache (without network before expiration, update in 3 minutes, seconds→ms, one in-flight for parallel calls), OAuth request form, models(),/balance.apiAgentStream.test.ts— splitSse, tool_calls by index, function_call in whole and in fragments, usage.apiAgentSession.test.ts— a full cycle of both flavors on a fake server: request format (functions vs tools), history (function vs tool), events, permission.registry.test.ts— available with / without switch, models from cache, scope.
Live run to the API using the owner’s key - manually (the “Check” button, then the task with the GigaChat agent).