Handbook: Inside Agents

Technical document - how agents are organized in code: registry, ACP sessions, built-in agent, swarm, memory, policies, MCP. User instructions - in Agents and models and Agent swarm.

Historical records by version go from bottom to top; Check current agent support at src/shared/agentCapabilities.ts and src/main/agents/registry.ts.

Basic agents (`src/main/agents/registry.ts`)

Agent How it starts Login What does it give?
Claude Code ACP adapter @agentclientprotocol/claude-agent-acp child Node process claude auth login the list of models comes from the adapter in runtime - for live testing on September 21, 2026 this is Fable 5.1 / Opus 5 / Sonnet 5 / Haiku 4.5; modes Manual Accept edits Plan Auto Bypass, effort
Codex @agentclientprotocol/codex-acp codex login or CODEX_API_KEY models and modes after the first session
Kimi Code kimi acp kimi login K2.8 / K2.7 / K3, thinking, modes default · plan · auto · yolo
OpenCode opencode acp opencode auth login dozens of providers, including Ollama and LM Studio via OpenCode config
Grok grok agent --no-leader stdio grok login or XAI_API_KEY The model is informed by the CLI itself after the session; auto-approval and worktree Pulse does not include
Local model built-in ApiAgentSession on top of OpenAI-compatible API the key is optional for local servers; gateway may require Bearer Ollama, LM Studio, LiteLLM, llama.cpp, vLLM and remote gateways; the code remains on the machine only if the server is running on it
GigaChat built-in ApiAgentSession (flavor gigachat) on top of GigaChat API authorization key (OAuth, scope PERS/B2B/CORP) GigaChat-2 / Pro / Max, Manual · Auto modes; TLS - CA NCA Ministry of Digital Development from resources/certs

All external agents speak to Pulse via ACP (session/new, prompt, tool_call, request_permission), so the transcript, graph, summaries and auto mode are the same for them.

Local model (`src/main/agents/apiAgentSession.ts`)

  • The server is specified in the agent card: address /v1 (Ollama, LM Studio, LiteLLM, llama.cpp presets) and an optional key. Pulse asks /v1/models — the list becomes the “Model” chip.
  • Optional JSON object chat_template_kwargs is set next to the address and key. For example, {"enable_thinking":false} disables reasoning on compatible Qwen3 models; Pulse passes the setting when checking ping and in every turn request. An empty field is not sent. Support and the required value are determined by the server and model.
  • Turn = cycle "chat/completions (stream, tools) → tool calls → results → model again,” up to 30 laps. Tools: read_file, write_file, edit_file, list_dir, search (ripgrep or traversal), bash (zsh in worktree, 2 min). Recording is only inside worktree.
  • Manual mode asks for permission to record and commands (card in chat, auto mode, “Allow in session” work like with ACP), Auto - executes it immediately. Reading with path (read_file, list_dir, search, code_map) also goes through policies, but in policyOnly mode: without a suitable rule, it is allowed silently, and a rule like “files with secrets - always ask” shows the card and when read, the ban rejects the call without a card.
  • The events are the same as for ACP: message, tool_call / tool_call_update with kind (read/edit/search/execute) and locations, usage (default window 32k), turn_complete.
  • Models must be able to function calling: qwen2.5-coder, qwen3, llama3.1, devstral, gpt-oss. A clean stream without a network is verified by a smoke test (apiAgentStream.ts) and mock server scratchpad/mock-openai.cjs.

GigaChat (`src/main/agents/gigachat/client.ts`)

  • The same ApiAgentSession, which is the same as the “Local Model”, but flavor: 'gigachat': request from functions + function_call: 'auto' instead of tools, history - assistant.function_call and role function instead of tool_calls / tool. Tools, permissions, events are general.
  • Authorization: OAuth (ngw.devices.sberbank.ru:9443/api/v2/oauth) by key from secrets, the token is cached and updated 3 minutes before expires_at; scope - from the card settings.
  • TLS: root NCA Mindigits from resources/certs/russian_trusted_root_ca.pem (extraResources), https.Agent({ ca }); transport - node:https, not undici.
  • “Check” button on the card: OAuth + /models, models - into the config option "model" cache (before checking - fallback GigaChat-2 / Pro / Max). Design - docs/gigachat.md.
  • The same key serves AI actions (commit message, stash, explanation, PR texts) - see the section “GigaChat as an AI Action Provider” below.

Auto mode (0.15.0)

  • In the chat session, the “Permissions” chip: Ask or Auto - allow everything. The car responds to all permission requests itself (session.autoApprove), writes “Allowed in automatic mode” to the feed and switches the mode of the agent itself to the nearest “automatic”: acceptEdits → auto → yolo → bypass (for Claude - Accept edits, as requested by the owner). Shutdown returns default / manual.
  • The agent has “Auto mode” in the settings for new sessions; the agent (profile) option has its own.
  • Warning: in auto the agent edits files and runs commands without confirmation. You can always cancel with the “Stop” button; diff and commit - manually.

Agent Options (Profiles, formerly My Agents) - v2

AgentProfile in pulse-settings.json: name, role, character (one line), instructions, base agent, model / mode / effort, auto mode, skills, color. There is no longer a separate “My Agents” page: profiles live in the “Agents” settings - in the card of each agent, section “Agent Options” (list of profiles with agent === kind, buttons edit/duplicate/delete, “Add option” opens ProfileEditor with a fixed base agent). So one agent can have several options: for example, two Claudes - a Sonnet developer and an Opus reviewer.

  • Role (role) — preset id from src/shared/roles.ts (lead, developer, reviewer, tester, documenter, refactorer) or custom. Selecting a preset substitutes the character and instructions from the library - but only into untouched fields (empty or still equal to the preset); your text is not overwritten. The role is visible as a badge in the list of options, in the “Team” chip of the composer, on the graph session node and in the SessionPanel.
  • Speed dial (button in the header of the “Agents” page): with one click creates a team - Lead (Opus), Developer (Sonnet), Reviewer (Sonnet), Tester (Haiku) on Claude Code or the first available agent; models - only from actually known registry variants, profiles with existing names are skipped (planQuickSet).
  • Instructions leaves in the first turn of the session: “Role: Reviewer. Instructions for agent “Name”: … --- Task: …” (buildFirstTurnText). This works with any base agent without editing adapters.
  • Skills (skills?: string[]) - names of skills from the “/” menu (same IPC pulse:list-skills, multi-select in ProfileEditor with filter at >10). This is not a restriction, but a recommendation: on the first turn, the line “Connected skills: /name1, /name2 - use them when appropriate for the task” is added. Empty - all skills are available to the agent as usual. Migration: missing field and invalid values → undefined (normalizeProfiles).
  • Tools (tools?: string[]) - constraint from the frontmatter of the library agent (library/agents/*.md, field tools: in Claude Code notation: Read, Write, ...). Parses when you select “From Library” (libraryAgentPrompt → parseAgentTools), in the editor it is shown as read-only chips. Applies it built-in agent only (ApiAgentSession): TOOL_SPECS filtered by list (profileToolsToInternal from shared/profileTools.ts: Read → read_file+code_map+ui_*, Grep → search+code_search, Glob → list_dir, Write/Edit/Bash - as is), and the call outside the list is rejected locally. For ACP agents (Claude, Codex, Kimi, OpenCode) the restriction does not apply - their tools are managed by their own CLI; in the UI it says this in the line tooltip.
  • Composer: a profile is selected in the agent chip (section “My Agents”), the “Team” chip adds more profiles - the task receives a session for each, everyone starts with one prompt in one worktree in parallel. In the sessions column, each session is labeled with a profile name. They have a common working copy: edits of participants fall on top of each other, and progress in a busy working folder is rejected (claimWorktree). We need separate copies per participant - this is a swarm, not a team; the same is said in the tooltip under the list of profiles.
  • Prepared task launched by the “Run” button in all non-running sessions.
  • Continue the session with the provider (0.30.12). The ACP session ID is stored in session.providerSessionId and survives the application restart. When a new process starts, it is transferred to the adapter: if the agent declared loadSession, the session rises through session/load with the entire history from the provider, and an excerpt of the transcript is not inserted into the prompt. Failure to load does not stop the launch - a new session begins, the context is sent in text, and a record of the reason is included in the transcript. What a specific adapter can do shows node scripts/acp-capabilities.mjs all: he asks for an opportunity and immediately tries it out. A refusal in an empty session does not mean a refusal after a completed turn. On September 21, 2026, Claude accepted an empty session in the same process, Codex declared an opportunity, but responded with an internal error. On October 1, a separate live ACP sample after the current turn showed Kimi and Codex continuing in the second process; Claude stopped at Authentication required. This is not yet a check for restarting Pulse itself, see. docs/testing/acp-session-resume.md.

Swarm (0.16.0)

Swarm - named composition of roles (shared/swarm.ts: architect, analyst, frontend, backend, security, product, tester, DevOps), which is launched on the repository with one button.

  • Composition stored in settings.swarms (Settings → Swarm): the participant has a role, agent, model, auto mode, leader, and his own instructions. Ready-made compositions - SWARM_PRESETS.
  • Launch (ipc.ts: launchSwarm): the task receives a session per role (session.swarmRole), task.swarm stores the presenter, participants, tasks and number of waves. Only the presenter with the text starts leadBrief (role, composition, protocol, brief); participants are waiting.
  • Protocol: the architect distributes tasks in blocks pulse-assign — lines “role: task” (parseAssignments understands id, Russian signatures, @role, continued on the next lines). Coordinator (main/swarm/coordinator.ts) on turn_complete The leader sends tasks to the participants (memberFirstTurn / assignmentPrompt), on turn_complete participant with an open task sends his last text to the presenter (reportPrompt); participant error - memberFailedPrompt. All turns go through the queue SessionManager.runTurn, so reports are not lost while the presenter is busy.
  • Limitations v1: one worktree per swarm (developers receive non-overlapping areas according to the architect’s instructions), report = last message of the progress, tasks only from the leader (the user can write to any participant directly in his chat).

Memory (0.17.0)

  • Task notes (task.notes): owner's text from the sessions column; The first turn of each task session and the swarm participants leaves the “Task Notes from the Owner” block (up to 2000 characters, shared/memory.ts: notesBlock / withContext).
  • Repository memory (main/memory/repoMemory.ts): userData/memory/<name>-<hash>.md. The “## date - task” entries are added by the swarm architect (result after closed tasks, once per wave, coordinator.ts), the “to memory” button in the sessions column (last response of the active session) and editing in the editor (sessions column or Settings → Repositories). Exposure (memoryExcerpt, 3000 characters along the line boundary) goes first to all sessions and to the architect’s brief.

The separate role Vault log is not yet connected to the worker; the confirmed lessons contract and test scenario are described in Confirmed lessons from the swarm.

Egress-allowlist of the swarm 24/7: not yet valid in sessions

packages/pulse-guard/src/egress.ts contains an HTTP/HTTPS proxy that checks addresses by AgentTaskManifest.egress, and egressProxyEnv for clients using proxy env. However startEgressProxy and egressProxyEnv are not called by non-test code: the swarm server checks the configuration 24/7, but does not launch the session executor. In a swarm of applications SessionManager starts the ACP agent via AcpSession.start with launch.env or runs a built-in API agent in the main process; these sessions do not have a manifest 24/7 with egress. Therefore, the presence of rules in the manifest does not currently limit the network of the running agent and does not create entries in pulse.egress_log from his turn.

One transfer HTTP(S)_PROXY in launch.env is not enough for the stated network perimeter: the agent code can open a direct socket, and some HTTP clients do not use these variables. Connection requires an executor that associates a specific manifest with a session, starts and closes its proxies, and forces all session network traffic to go through an auditable path (for example, process network isolation). End-to-end verification should run a real agent process, check allowed and denied addresses, direct connection attempt and log. Until this is done, proxy tests only prove its behavior for requests already routed through it.

Policies, budgets, sandbox, audit (0.18.0)

  • Politicians (shared/policy.ts: decidePolicy): check order in askPermission — role restriction (review → prohibition of edits and commands) → rules from top to bottom (first suitable one) → “ask” → auto agent / auto session mode / “Allow in session” → user card. Rule context: title, kind, command and paths from rawInput / locations (ACP sends them to requestPermission), the role of the swarm.
  • Budget (shared/budget.ts, ipc.ts: checkBudget / guardBudget): by usage-events are counted as a sum costUsd task sessions against limit (task → general); warn - notification once, over - cancel all sessions task.budgetExceeded, refusal of new turns.
  • Sandbox (apiAgentTools.ts: sandboxProfile): sandbox-exec -p with writing only to worktree, tmp and caches; network and reading without restrictions.
  • Audit (shared/auditReport.ts): buildAuditMarkdown / buildAuditJson from task, sessions, transcripts and tape; Permit Decisions - Records kind: 'permission' tapes (onPermissionDecided).

External MCP servers (0.19.0)

  • Config - settings.mcpServers (McpServerConfig: stdio/http, agents, hint, {worktree}).
  • ACP agents: SessionManager.ensureSession → AcpSession.start(launch, cwd, mcpServers) → session/new { mcpServers } (ACP format: env as name/value pairs).
  • Built-in agent: ApiAgentSession.connectMcp raises McpStdioClient to server, list tools/list turns into ToolSpec with names mcp__<id>__<tool>; runCall routes them to runMcpCall (tools/call); policies do not apply to MCP calls (v1 - read-only by assigned servers).
  • Server hints - the “Connected MCP servers” block in withContext first turn.

Swarm: own worktree, merging, auto-repeat (0.20.0)

  • ipc.launchSwarm → memberGit.createMemberWorktree for roles kind dev (branch <task.branch>-<role>, session.cwd); SessionManager.ensureSession takes session.cwd ?? task.worktreePath.
  • Coordinator: send() → deps.syncMember (commit uncommitted, merge task branches into participant’s worktree; conflict → task failed + to the architect); finishAssignments() → deps.integrateMember (commit the participant’s work, merge into the task’s worktree; conflict → merge --abort, note to the architect) → assignment.merge.
  • Auto repeats: onMemberError → attempts < MAX_ATTEMPTS(2) → task repeated, otherwise failed + memberFailedPrompt. Custom tasks: assignFromUser (from: 'user', does not count waves).
  • Plan docs/harness-plan.md closed at 0.22.0.

GigaChat: scope auto-selection swarm: task timeout (0.22.1)

  • GigaChatClient.requestToken: scope order - from settings, then the rest GIGACHAT_SCOPES; isScopeMismatch (400 + “scope” in the body) → next, another error → immediately out; success under a different scope → currentScope, opts.onScopeResolved(scope) (ipc saves in agents.gigachat.scope; “Check” - via GigaChatCheckResult.scope).
  • SwarmCoordinator.start()/stop() - watchman once every WATCHDOG_INTERVAL_MS; checkTimeouts(now): tasks sent with sentAt + ASSIGNMENT_TIMEOUT_MS <= now → deps.cancelTurn(sessionId) + onMemberError(...) (repeat/failure); timedOut - sessions whose turn_complete(cancelled) is not considered a report. Deps: listSwarmTasks, cancelTurn.

Built-in Agent Context (0.22.0)

  • shared/chatContext.ts: estimateTokens (Cyrillic ≈2.5 characters per token, the rest ≈3.5), messagesTokens, splitTurns (system / summary / turns from user to user), trimToolOutputs, summarizeTurn (request, tools with mainArg and counter, write/edit files, total), mergeSummary (one report prefixed SUMMARY_PREFIX, limit 6000 characters, old turns disappear), compactMessages — steps: soft trimming of old ones → summary of old ones (except KEEP_TURNS = 2) → hard trimming of recent ones → summary of everything except the current one → trimming of the current one without the last message. Threshold 75% window, target 50%.
  • ApiAgentSession: maybeCompact() before each request (and between circles of the same turn), calibration = server prompt_tokens / score (0.5…4), event thought with a result; opts.contextSize ← AgentSettings.contextSize (Settings → Agents → “Context window”, settings/ContextWindowRow.tsx), default DEFAULT_CONTEXT_SIZE = 32k.

Instructions versions (0.21.0)

  • shared/promptHistory.ts: recordVersion(history, owner, text, at, note) — new version only when text changes (trim), limit MAX_PROMPT_VERSIONS = 30; latestVersion, dropOwner, diffLines (line by line, without regard to order). Owners: profileOwner(id) → profile:<id>, swarmMemberOwner(swarmId, memberId) → swarm:<id>:<member>.
  • SettingsStore.patch: at profiles/swarms writes versions of changed instructions and erases the history of deleted ones; promptVersionOf(owner, text) — session version (the old profile without history gets v1 “from the settings”).
  • ipc.createSessionRecord and launchSwarm put session.promptVersion; the sessions column shows “inst. vN". UI - settings/PromptHistory.tsx under the profile instructions field (ProfileEditor) and swarm member (SwarmPage).

Sessions running outside of Pulse (Phase 6.4)

Agent raised with hands in terminal (claude, codex, ...), announces itself with hooks to the local bridge 127.0.0.1 (main/agents/externalStatus.ts): POST /session — registration and status, POST /permission - blocking permission request that Pulse shows with its card. The bridge sends a list to the renderer ExternalAgentSession (store.externalAgents): agent, pid, folder, title, status, last event time.

Bridge address and token - discovery file os.tmpdir()/pulse/agent-<pid>.json: catalog 0700, file 0600, someone else's uid is rejected by readers (hook mcp/pulse-agent-hook.sh, mcp/pulse-mcp.cjs, cleaning stale - in the service itself). The hook parses discovery through node (sed replaced values ​​using JSON, audit 24.09 #226/#338); his stand is running real bash against fake discovery files in src/main/agentHook.test.ts.

Where can it be seen

  • Dashboard, “External Agents” panel - the whole list. The line shows the task if the session folder is in its working copy; click opens the task. It didn’t match - the line honestly says “without a task”: such a session will not be included in the graph.
  • Problem graph - view node external in the sessions layer, next to and after your own. An edge to a task means exactly one thing: the session is in a working copy of this task. Whether she is occupied with her goal, Pulse does not know and does not state this anywhere.
  • Statistics rake — the line “Outside Pulse” as a separate number. “Sessions”, “Tools” and “Cost” do not include other people’s sessions: Pulse does not see their turns, and adding them to your own means inflating the total.

Frontier of knowledge

Someone else's session comes with one status. Pulse does not have a transcript, turns, calls, cost, context or model - and they are not completed by analogy with their session:

  • the card instead of counters shows “no turns visible”;
  • the node panel lists the unknown in words (“What Pulse doesn’t see”), rather than with dashes: a dash in place of a number is read as zero;
  • the node has no children and no sessionId — there is nothing to open under it and there is nothing to switch the chat to;
  • In order for calls to be included in the graph, the session must be conducted from Pulse.

An exception is the cost, context and limits of a Claude Code subscription (604, 10/04/2026): if a person turned on the toggle switch “Money, context and limits in the agent card”, the Claude Code status bar is wrapped mcp/pulse-statusline.sh passes them on to the bridge (shared/agentUsage.ts, field usage sessions), and the card shows them by section; the node tooltip then doesn't say that they are not visible (externalUnknown). No data - no section, not “$0”; This money is not included in the “Cost” of the reiki.

Where is the code

  • shared/externalGraph.ts — clean part with tests: comparing the session folder with a working copy of the task (taskIdForExternalSession, externalSessionsOfTask, splitExternalSessions), general status signatures and EXTERNAL_UNKNOWN - a list of what we don't know. The register of the path is not intentionally normalized: a letter match is a fact, a match “up to the case” is a guess, and it is more honest to leave a dissimilar spelling without a task.
  • graph/externalNodes.ts — ExternalNodeInfo and assembly of nodes. The statuses are translated as follows: working → running, waiting → pending (“waiting for a response” is a hanging request for permission, that is, really “waiting for you”), idle → completed (calm state; pending I would color the card alarmingly and light a halo). This translation does not affect the pill: it is colored by its own bridge dictionary (exc-* in graph.css).
  • graph/layout.ts — BuildOptions.external and GraphStats.external; the thread itself is moved to externalNodes.ts, so as not to grow an already overgrown file.
  • graph/AgentGraphView.tsx - selection by tasks and externalSignature. The graph model does not depend on the list, but on its fingerprint: the bridge sends an update for each event of the external agent, and usually one thing changes in it lastEventAt, which is not on the card. Without a fingerprint, a complete recalculation of the model and layout would take place several times a second for nothing (price - see below). scale.md). Therefore lastEventAt It doesn’t lie in the node either: the panel reads the age of the event from the live list, otherwise it would show a frozen number.

GigaChat as an AI action provider (`main/ai/providers/gigachat.ts`)

GigaChat is no longer just an agent: it is now an AI engine provider - commit message, stash name, explanation of changes, PR texts, atomic commit plan, AI conflict resolution. It all comes through AIService.generate, so there is only one provider for all actions.

  • There is only one key. needsApiKey: false (otherwise the AI page would show the second field of the key, which does not exist), the truth about access is given by the new optional AIProvider.hasCredentials. Key, scope and models AIService gets through AIServiceDeps.gigachat() from the same places as the agent: secrets.gigachatAuthKey, gigachatScope(ctx), cache config option “model” card (otherwise GIGACHAT_FALLBACK_MODELS). onScopeResolved writes the selected scope into the card.
  • Transport lives longer than the provider. providerFor collected by the provider for each call, therefore AIService holds cacheGigaChatTransport: one GigaChatClient for a session until they change authKey and scope. Without it, the three-minute token cache inside the client never worked - the client died along with the call, and each action paid with a new OAuth, reading the PEM root of the NCA Mintsifra and a new https.Agent. fresh: true (the “Check” button) bypasses the cache: the response from the cache would mean “we still have the token,” and not “the key is valid.”
  • Error codes. OAuth 401/403 and “did not fit any scope” → AI_INVALID_KEY; missed call → AI_NETWORK; HTTP OAuth failure → AI_PROVIDER. U /chat/completions: 401/403 → AI_INVALID_KEY, 402/404/429 → AI_PROVIDER with explanation (statusHint), empty answer → AI_PROVIDER. Each text about the key contains the address “Settings → Agents → GigaChat card”: window (renderer/src/ai.ts: namesPlace) shows the provider’s words only when he himself named the section, otherwise it substitutes general advice about “Settings → AI”.
  • UI. settings/AiPage.tsx: GigaChatKeyRow - instead of an input field, key status, go to the agent card and “Check” (pulse:ai-verify-key → verifyKey → real OAuth).
  • What is not. Speech transcripts via GigaChat (voiceCapability responds with a refusal with a ready output), streaming output from AI actions (not a single provider has it), the rest of the token package (/balance only the agent asks). There was no live run on Sber's combat key along this road - all checks were on a fake server.

Where next (in development)

  1. Roles in the team - behavior: the leading agent distributes subtasks, participants report - exchange of results between sessions (now everyone sees one worktree, but not each other’s transcripts; roles and a library of instructions already exist).
  2. Mixed topics: different base agents in one team (Claude reviews, local model writes tests) - already possible through profiles, a team summary on the board is needed.
  3. Import/export JSON profiles.
  4. Evaluating the team's results: comparing session diffs, choosing the best, merging.
  5. GigaChat via the same ApiAgentSession — done (see section “GigaChat” above); GigaChat as an AI Action Provider - also done. Next are live runs with the combat key (neither the agent nor the AI ​​actions were tested on it) and the exact sizes of the models’ context windows.

Working copies and acceptance (09/20/2026)

New teams with regular profiles, like swarm developers, have separate worktrees. See the result of the session on the “Diff → Problem Result” tab by selecting the author. After verification, the “Merge with issue” button transfers its work to the general branch. Acceptance of the overall result is performed separately; completing the agent's turn only means completing the request. Old issues are not automatically marked as accepted.

“Open in Editor” opens the selected working copy; this allows you to continue using your familiar IDE. When control is transferred to another process, Pulse restores the goal, profile, notes, memory, and last turns. For the full history, a transcript remains.