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 { NativeLaunch } from '../../engines/nativeLaunch.js'
/**
* Relaunch helpers: what a restart, a retarget, a restore or a resume needs to bring an agent's pane
* back. Its launch overrides, rebuilt from the row (an API's key as saved now); the web-search decision
* refreshed; a permission flag the engine no longer takes dropped, rather than the pane; and the history made
* resumable (Codex's rollout, engines/launchPrep.ts), with the tail moved to its new length.
*
* Moved verbatim out of `runForeground` (the core boundary, step 10: docs/design/2026-10-03-harnessd.md).
*/
import { join } from 'node:path'
import { env } from '../../config/env.js'
import { prepareResume, repairedItemsName } from '../../engines/launchPrep.js'
import { bringPiSessionHome } from '../../lib/piSessionHome.js'
import { gridConfigRoot } from '../../lib/gridConfigDir.js'
import { dropPermissionFlagIfUnsupported } from '../../lib/engineLaunch.js'
import { gridUnavailable, type GridLaunchAnswer, type GridLaunchRequest } from '../../lib/gridLaunchWire.js'
import { buildLaunchOverrides, type LaunchOverrides, type LaunchOverridesDeps, type LaunchOverridesResult, type LaunchSource } from '../../lib/launchOverrides.js'
import type { ModelsPort } from '../api.js'
import { sid } from '../../lib/log.js'
import { prepareInstructionWrites } from '../../scm/scmProjects.js'
import type { registry, RegisteredSession } from '../../lib/registry.js'
/**
* The models service's grid launch, as every launch in the core asks it (`ModelsPort.gridLaunch`): its answer, or,
* when models is down or answers nothing usable, the refusal that says so (`gridUnavailable`), never a launch on
* the engine's own login and never a wait past the call's bound (core/serviceLinks.ts). A saved API's endpoint
* the answer read is one the core's grid assignment recognises from then on, as when the core read it itself.
*/
export function gridLaunchThrough(models: () => Pick<ModelsPort, 'gridLaunch'>) {
return async (request: GridLaunchRequest): Promise<GridLaunchAnswer> => {
let answer: GridLaunchAnswer
try { answer = await models().gridLaunch(request) } catch { return gridUnavailable(request.engine, request.override) }
return answer
}
}
export interface LaunchHelperDeps {
/** Capture dispatch authority before a service can yield to Stop or a replacement binding. */
authority: (agentId: string) => () => boolean
/** Writes the saved APIs' tool instructions into the agent's folder before it launches. */
prepareApiTools: (cwd: string | null | undefined, engine: string) => void
launchOverridesDeps: LaunchOverridesDeps
setGridLaunch: typeof registry.setGridLaunch
/** Moves a session's tail to a byte (Watcher.setTail). */
setTail: (sessionId: string, offset: number) => void
}
export function createLaunchHelpers({ authority, prepareApiTools, launchOverridesDeps, setGridLaunch, setTail }: LaunchHelperDeps) {
// Whatever the source (the row itself, or a grid override the desktop just sent), the agent's DSH,
// workspace, named agent and who started it come from the row: a retarget must not silently drop the harness
// the agent is, or bring a pane opened as `harness-compute` back as a general session.
// An agent on a saved API's model relaunches with that API's endpoint and key as saved now, so a key
// pasted since takes effect, and a removed API is refused rather than kept on its old key: the models
// service reads them as it builds the launch (`buildLaunchOverrides`, `refresh`).
const relaunchOverrides = async (session: RegisteredSession, source: LaunchSource = session, operationCurrent: () => boolean = () => true, native?: NativeLaunch, configKey = session.agentId): Promise<LaunchOverridesResult> => {
const dispatchCurrent = authority(session.agentId)
const current = () => operationCurrent() && dispatchCurrent()
session = structuredClone(session)
const changed = { ok: false, error: 'AGENT_CHANGED', detail: 'The harness changed or stopped during launch preparation.' } as const
if (!current()) return changed
const result = await buildLaunchOverrides(launchOverridesDeps, session.engine, { dsh: session.dsh ?? null, dshRuntime: session.dshRuntime ?? null, swarmSkill: session.swarmSkill, cwd: session.cwd, agent: session.agent ?? null, scmLaunch: session.scmLaunch ?? null, startedBy: session.startedBy ?? null, launchArgs: session.launchArgs, ...source, gridLaunch: source.gridLaunch ?? null }, configKey, current, native)
if (!current()) return changed
if (!result.ok && (result.unavailable || result.error === 'AGENT_CHANGED')) return result
// Saved-API instructions remain available after an ordinary semantic refusal, as before.
// A missing dependency or revoked operation must leave these files untouched.
await prepareInstructionWrites(session.cwd)
if (!current()) return changed
prepareApiTools(session.cwd, session.engine)
if (result.ok && session.externalResume?.request.engine === session.engine) {
result.overrides.extraArgs.push(...session.externalResume.session?.launchArgs ?? [])
}
return result
}
/**
* A restart or a post-reboot restore rebuilds the ROW's own launch, and the machine may decide
* differently about web search this time than it did when the row was written (an administrator
* pinned `/etc/hermes` since, or unpinned it). The override is the row's already; what is
* refreshed is the decision, so the frame describes the pane that actually came up. Retarget
* does not go through here — its override is new, and it records the pair itself once the move
* has succeeded.
*/
const refreshGridWebSearch = (agentId: string, overrides: LaunchOverrides): void => {
if (overrides.gridLaunchRecord) setGridLaunch(agentId, overrides.gridLaunchRecord)
}
/**
* The permission this relaunch can actually ask for. Nobody is waiting on a restart, a retarget, a
* restore or a resume, so an engine that no longer takes the row's flag costs it the mode, not the
* harness — the alternative is a pane of help text, or no pane at all (openharness#285).
*
* The row is NOT rewritten. `permissionMode` is the person's recorded choice and `setPermissionMode`
* is fill-only for that reason; an engine put back the way it was gets Auto again on the next
* relaunch, with nobody having to ask for it twice. The row stops CLAIMING the mode on its own:
* discovery re-derives `bypassPermission` from the live argv on every pass (`setBypassPermission`
* above), so a launch without the flag reads as one within a reconcile.
*
* ⚠️ Its alias in runForeground is DECLARED BEFORE THE RESTORE PASS, and has to stay there:
* `restoreAgents` calls `buildLaunch` for every pane it rebuilds, which asks this, during start-up.
*/
const downgradedPermission = async (
session: RegisteredSession,
bypassPermission: boolean,
what: string,
native?: NativeLaunch,
): Promise<{ permissionMode?: string | null; bypassPermission?: boolean; nativeHold?: string }> => {
const { choice, droppedFlag, nativeHold } = await dropPermissionFlagIfUnsupported(session.engine, {
permissionMode: session.permissionMode ?? null,
bypassPermission,
}, undefined, native)
if (droppedFlag) {
console.warn(`[agent] ${what} ${sid(session.agentId)} · ${session.engine} does not take ${droppedFlag}`
+ ` · starting in Ask · update ${session.engine} to get ${session.permissionMode ?? 'Auto'} back`)
}
return { ...choice, ...(nativeHold ? { nativeHold } : {}) }
}
const prepareSessionResume = (session: RegisteredSession): void => {
if (session.engine === 'pi') {
// A Pi an older grid launch moved into the daemon's own folder resumes from its own home now.
const roots = [gridConfigRoot(), join(env.ADAPTER_DATA_DIR, 'grid-launch-config')]
const sessions = process.env.PI_CODING_AGENT_SESSION_DIR || join(process.env.PI_CODING_AGENT_DIR || join(env.PI_HOME, 'agent'), 'sessions')
// Best effort: this runs after the old Pi has stopped, and a copy that cannot be made must not cost the
// relaunch. Pi then resumes what it can find, as it did before.
try {
const home = bringPiSessionHome(session.transcriptPath, roots, sessions)
if (home && home !== session.transcriptPath) console.log(`[resume] ${sid(session.agentId)} · pi's conversation brought home · ${home}`)
} catch (error) {
console.warn(`[resume] ${sid(session.agentId)} · could not bring pi's conversation home · ${error instanceof Error ? error.message : error}`)
}
}
const repair = prepareResume(session)
if (repair.repairedItems) {
// The rollout we tail was just shrunk in place. Move the tail to the repaired length now, before
// the resumed engine appends, or the watcher would read the whole repaired history as new lines
// and the live normalizer would replay the conversation into web/device. See Watcher.setTail.
if (repair.repairedBytes !== undefined) setTail(session.sessionId, repair.repairedBytes)
console.log(`[resume] repaired ${repair.repairedItems} ${repairedItemsName(session.engine)} · backup: ${repair.backupPath}`)
}
}
return { relaunchOverrides, refreshGridWebSearch, downgradedPermission, prepareSessionResume }
}