The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import type { ActivityFrame } from './turnActivity.js'
/**
* The one shape an agent takes on the wire.
*
* Every client — the web, the device, and the desktop window — rebuilds its whole agent from
* whichever of these frames arrived last: `agents_list` replies and `agent_synced` pushes are the
* same object, not a snapshot and a patch. So a field this function forgets is not merely missing
* from one frame; it is ERASED on the next push from whatever an earlier frame had reported.
*
* That is not hypothetical. This module exists because there were two hand-maintained copies of the
* shape — one in `cli.ts` behind `agent_synced`, one in `backendSocket.ts` behind `agents_list` —
* and `grid` was added to the second only. The desktop showed an agent's grid correctly the moment
* it was moved, then the next reconciliation pushed a frame with no `grid` at all, the app read that
* as "on no grid", and its "N running agents are on an older target" banner came back for agents
* that were already exactly where the user had put them.
*
* Pure on purpose: the two callers own the registry, so what they know (is the terminal available,
* which model did the runtime profile resolve) is passed in rather than looked up here. That is what
* makes the shape testable without a registry, which is the whole reason the drift went unnoticed.
*/
import { agentProject } from './agentProject.js'
import { describeScmProject } from '../scm/scmProjects.js'
import type { ScmDescription } from '../scm/types.js'
import { sessionGitContext, SessionGitContextReader, type SessionGitContext } from './sessionGitContext.js'
import { sessionGitHistory } from './sessionGitHistory.js'
import { transcriptActivityAt } from './transcriptActivity.js'
import type { AgentTokenUsage } from './agentUsageWire.js'
import type { AgentOutputStats } from './agentOutputStats.js'
import type { GridAssignment } from './gridAssignment.js'
import type { GridWebSearchStatus } from './gridLaunchWire.js'
import type { AgentGridTarget, GridAnnotation } from './gridAnnotation.js'
import { isNameChosen, projectDisplayName, sessionDisplayTitle, type RegisteredSession } from './registry.js'
import { engineCanFork } from './forkAgent.js'
import { resumeMode, type ResumeMode } from './resumeCapability.js'
import type { DshVerdict } from '../dsh/verdict.js'
/**
* The grid block on the wire: where the agent's inference goes, and — when the daemon built the
* launch — whether it can search the web. `webSearch` is absent, not null, when there is nothing to
* say: a discovered grid agent, or a row from before the daemon recorded it. The app shows nothing
* for absent and for `on`; the two degraded words each get a sentence.
*/
export type GridFrameBlock = GridAssignment & { webSearch?: GridWebSearchStatus } & Partial<GridAnnotation>
/**
* One agent as it travels to every client.
*
* A `type` rather than an `interface` so it stays assignable to the `Record<string, unknown>` the
* frame senders take — an interface gets no implicit index signature.
*/
export type AgentFrame = {
id: string
sessionId: string
userId: string
name: string
/**
* Whether a person chose `name` (they renamed the agent), as against the name it was created with or its session
* title (registry.ts, `isNameChosen`). A client sends only a chosen name to the Swarm (task #2920). Absent from a
* daemon before it: a client reads that as "unknown" and sends nothing.
*/
nameChosen: boolean
/**
* What the agent is on, in its own words — the session title (Claude Code's, Codex's), cleaned;
* null when there is none or it is the name already. It is usually the name too (registry.ts,
* projectDisplayName), but not once the person renames the agent, and a client searching for
* "board fab check" must still find it by this, not by luck in a recap.
*/
title: string | null
status: string
activity: ActivityFrame | null
closePlan: { state: 'waiting' | 'failed'; detail?: string } | null
closeSupported: boolean
launch: NonNullable<RegisteredSession['launch']>
identityHold?: string
createdAt: string
updatedAt: string
/**
* When any app last opened this agent (`agent_update {opened: true}`), stamped by this daemon's
* clock (registry.ts, `markOpened`). ALWAYS present: null means nobody has opened it yet, while an
* absent key means a daemon too old to keep the stamp — the distinction a client needs to tell "never
* opened" from "cannot say". A client's "last used" is the later of this and `updatedAt`, so every
* app orders the same agents the same way.
*/
lastOpenedAt: string | null
/** Cached usage from this conversation's owning machine; null means unreported, never zero. */
tokenUsage: AgentTokenUsage | null
outputStats: (AgentOutputStats & { updatedAt: string }) | null
tmuxPane: string | null
terminal: { available: boolean; primary: string; runtimes: RegisteredSession['runtimes'] }
engine: RegisteredSession['engine']
selectedModel: string | null
grid: GridFrameBlock | null
codexHome: string | null
/** The Claude profile folder (CLAUDE_CONFIG_DIR) this agent launched against; absent or null for the default account. */
claudeHome?: string | null
/** The extra launch words the owner saved for this agent (`agent_restart`'s `launchArgs`); absent when it has none. */
launchArgs?: string[]
/** The workspace as its SCM describes it, with `kind` (`git`, or `none` for a folder no SCM claims);
* every other field is exactly what `agentProject` reports (scm/types.ts). */
project: ScmDescription | null
/** Additive display context; project/cwd remain the registered launch workspace. */
gitContext: SessionGitContext
/** The domain-specific harness this agent was created as, or null for a plain engine. */
dsh: string | null
/** Its display name from the installed manifest; null when unknown here (not installed, plain engine). */
dshName: string | null
/** Where this agent's viewer is being served right now, or null when it has none up. */
viewerUrl: string | null
/** What its viewer pane is called ("3D Viewer", "Marp Viewer"); null with no viewer or none known. */
viewerName: string | null
/** The DSH's last verdict for this workspace, reduced for the pane header; null when none yet. */
verdict: DshVerdict | null
/** The agent this one was forked from (`agent_fork`), or null — a real answer, like `dsh: null`. */
forkedFrom: { agentId: string; name: string } | null
/**
* The harness on this machine whose agent started this one (`harness new` or `harness_start` from its pane), by its
* agent id, or null: the person, an agent outside Harness, or one on another machine. A window that shows that
* harness in a tab opens this one beside it when it first sees it live, and its header says "started by" with the
* starter's current name (desktop `Agent.parentAgentId`).
*/
parentAgentId: string | null
/** `agent` when another agent started this harness, wherever that agent runs (registry `startedBy`); null when the
* person did. The agent verbs read it to keep such a harness from starting harnesses itself (agentClient/model.ts
* `callerOf`): `parentAgentId` names only a starter on this machine. */
startedBy: 'agent' | null
/** Whether `agent_fork` can do anything for this engine (lib/forkAgent.ts) — natively, or by a
* handoff. A client hides the Fork action on a false rather than offering a button that refuses. */
forkable: boolean
/**
* How much a Pause of this harness can promise to bring back (lib/resumeCapability.ts):
* `'shell'` (a terminal — a fresh shell in the same tile), `'conversation'` (this engine reopens
* the one it was in) or `'fresh'` (it comes back, as a new conversation). Every value is
* pausable; a client words the button from this rather than keeping its own copy of the engine
* table, which is how the two drifted before.
*/
resumeMode: ResumeMode
/**
* The launch choices a client needs to open ANOTHER agent like this one — the desktop's Clone
* (`agent_create` with the same `permissionMode`, `bypassPermission` and `agent`). Read off the
* registry row, never off the live process. Each null is a real answer: a row from before the
* choice existed, or an agent Harness did not launch, has none to report — and a clone of one
* falls back to the client's own defaults rather than to a guess made here.
*/
permissionMode: string | null
bypassPermission: boolean | null
/** The engine's named agent (`agent_create`'s `agent`); `namedAgent` on the wire so an agent
* object never carries a key called `agent`. */
namedAgent: string | null
}
/** What the daemon knows about an agent's DSH — looked up by the caller, never here. */
export interface AgentDshContext {
/** The harness's CURRENT id — an agent created under a former name (`formerly`) reports the new one. */
id: string | null
name: string | null
viewerUrl: string | null
/** manifest.ts, dshViewerName. */
viewerName?: string | null
verdict: DshVerdict | null
}
/** What the caller knows and this module deliberately does not look up for itself. */
export interface AgentFrameContext {
/** Evaluated after asynchronous projection, so old snapshots cannot revive work. */
activity?: () => ActivityFrame | null
/** The runtime profile's answer for this session, or null when there is none. */
selectedModel: string | null
/** `registry.terminalAvailable(agentId)` — the caller already holds the registry. */
terminalAvailable: boolean
tokenUsage?: AgentTokenUsage | null
/** The DSH companions' state for this agent; absent when the caller has none to give. */
dsh?: AgentDshContext | null
/** What the models service says of the grid the agent is on (core/api.ts `ModelsPort.annotation`): from
* memory, never I/O. Absent when the caller has none to give, and then the frame says nothing of it. */
gridAnnotation?: (grid: AgentGridTarget) => GridAnnotation | null
}
/**
* When the conversation last moved, in epoch ms: dated work in the transcript, else the last time the engine
* reported in (a hook, or a session bind — the agent's creation at the latest).
*
* ⚠️ Never the registry row's `touchedAt`. That is bookkeeping: discovery used to rewrite it on every
* pass, so falling back to it stamped every agent without a readable transcript "now"
* — and a client sorting by recency put exactly those agents above the ones just used. File mtime is
* bookkeeping too: an idle transcript can be rewritten without a new conversation event.
*
* "The agent's creation at the latest" is the part that was missing: a row no hook has ever reached —
* a bare terminal, an engine still starting, a harness opened from the catalog — carries
* `lastHookAt: 0`, and answering the epoch made a client render its age as 20719 days ("20719d") and
* sort it below everything. Creation is a real answer for "nothing has happened yet"; zero is not.
*
* Every step is a stamp the row already carries, never a fresh clock read: a client compares this
* field to decide whether an agent changed at all (the desktop's `agentsEqual`), so a value that
* moves on its own would redraw the row on every sync and reset its age to "0m" forever.
*/
export async function lastActivityAt(s: RegisteredSession): Promise<number> {
return await transcriptActivityAt(s.transcriptPath, s.engine)
?? (s.lastHookAt || s.boundAt || s.registeredAt)
}
function frameTitle(s: RegisteredSession): string | null {
const title = sessionDisplayTitle(s)
return title && title !== projectDisplayName(s) ? title : null
}
/**
* One agent as every client consumes it. `updatedAt` is {@link lastActivityAt}, so a client sorting by
* recency follows the conversation rather than the daemon's housekeeping; `lastOpenedAt` is the other
* half of "last used" — when a person last opened it, from any app — and a client sorts by the later
* of the two.
*/
const gitContexts = new SessionGitContextReader()
export async function agentFrame(
s: RegisteredSession,
{ selectedModel, terminalAvailable, dsh, tokenUsage, activity: contextActivity, gridAnnotation }: AgentFrameContext,
): Promise<AgentFrame> {
// The git context is git's own display projection and keeps reading git directly; the frame's
// `project` goes through the SCM seam. Both resolve through agentProject's shared reader, so the
// seam adds no Git process.
const home = agentProject(s.cwd)
const context = gitContexts.read(JSON.stringify([s.agentId, s.sessionId, s.engine, s.codexHome, s.registeredAt]), async () => {
const saved = await sessionGitHistory.get(s)
const value = await sessionGitContext(await home, tokenUsage?.work, undefined, saved)
value.history = await sessionGitHistory.observe(s, value)
return value
})
const [project, updatedAt, gitContext] = await Promise.all([describeScmProject(s.cwd), lastActivityAt(s), context])
return {
id: s.agentId,
sessionId: s.sessionId,
userId: '',
name: projectDisplayName(s),
nameChosen: isNameChosen(s),
title: frameTitle(s),
status: s.active ? 'active' : 'offline',
activity: contextActivity?.() ?? null,
closePlan: s.closePlan ? { state: s.closePlan.state, ...(s.closePlan.detail ? { detail: s.closePlan.detail } : {}) } : null,
closeSupported: true,
launch: s.launch ?? { state: 'ready' },
...((s.identityHold || s.interpretationHold || s.admissionHold) ? { identityHold: s.identityHold || s.interpretationHold || s.admissionHold } : {}),
createdAt: new Date(s.registeredAt).toISOString(),
updatedAt: new Date(updatedAt).toISOString(),
// Null, never omitted, for the reason the module doc gives: a push without the key would erase
// the open an earlier frame had reported.
lastOpenedAt: s.lastOpenedAt ? new Date(s.lastOpenedAt).toISOString() : null,
tokenUsage: tokenUsage?.totalTokens != null
? { totalTokens: tokenUsage.totalTokens, updatedAt: tokenUsage.updatedAt,
...(tokenUsage.inputTokens == null ? {} : { inputTokens: tokenUsage.inputTokens }),
...(tokenUsage.outputTokens == null ? {} : { outputTokens: tokenUsage.outputTokens }),
...(tokenUsage.cachedTokens == null ? {} : { cachedTokens: tokenUsage.cachedTokens }),
} : null,
outputStats: tokenUsage?.output ? { ...tokenUsage.output, updatedAt: tokenUsage.updatedAt } : null,
tmuxPane: s.tmuxPane || null,
terminal: { available: terminalAvailable, primary: s.primaryRuntimeKey, runtimes: s.runtimes },
engine: s.engine,
selectedModel,
// Where this agent's inference actually goes, so a client can tell which agents a newly picked
// grid has left behind. Read off the live process by discovery; carries no credential. Null is
// a real answer ("on no grid") and must be sent as one — omitting the key would make every push
// indistinguishable from a daemon too old to know about grids. The web-search status rides on
// the block — decided by the launch, kept on the row — so it is gone the moment the block is. So do
// that grid's `state` and a `note` when the agent's model will not answer (issue 03), read from what
// the model list last showed — no I/O, and absent for a grid this daemon is not tracking.
grid: s.grid ? { ...s.grid, ...(s.gridWebSearch ? { webSearch: s.gridWebSearch } : {}), ...gridAnnotation?.(s.grid) } : null,
// The Codex profile folder this agent launched against, if one was chosen instead of the
// engine's own login. Codex only; null is a real answer ("uses ~/.codex") for the same reason
// `grid: null` is above.
codexHome: s.codexHome ?? null,
claudeHome: s.claudeHome ?? null,
...(s.launchArgs?.length ? { launchArgs: [...s.launchArgs] } : {}),
project,
gitContext,
// All five are real answers when null, for the reason the module doc gives: a frame that omits
// them would erase a viewer URL or a verdict an earlier frame had reported.
dsh: dsh?.id ?? s.dsh ?? null,
dshName: dsh?.name ?? null,
viewerUrl: dsh?.viewerUrl ?? null,
viewerName: dsh?.viewerName ?? null,
verdict: dsh?.verdict ?? null,
forkedFrom: s.forkedFrom ? { agentId: s.forkedFrom.agentId, name: s.forkedFrom.name } : null,
parentAgentId: s.parentAgentId ?? null,
startedBy: s.startedBy === 'agent' ? 'agent' : null,
forkable: engineCanFork(s.engine),
resumeMode: resumeMode(s.engine),
permissionMode: s.permissionMode ?? null,
bypassPermission: s.bypassPermission ?? null,
namedAgent: s.agent ?? null,
}
}