Skip to content

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.

9.6 KB
Raw Blame
/**
 * What the person lets agents do with Harness (docs/design/2026-10-11-agent-client.md): three of the account's
 * experiments, Settings ▸ Experimental (backend lib/experimentalSettings.ts), each off until the person turns it on.
 * They were each computer's own Settings ▸ Agents, on by default, until the owner made them the account's, one choice
 * for every computer, and off for all: none had been announced (2026-10-12).
 *
 * This computer's daemon keeps a copy in its data folder, `agent-settings.json`, because nothing that reads them may
 * wait on the network: every launch (whether its agent is told how to start others, and whether one another agent
 * started says so in its pull requests), `harness new` when an agent runs it (whether it may), and Agent Messages
 * every 2 s. The core's sync (core/experiments.ts `createAgentSettingsSync`) is its only writer, and writes it for an
 * account and this computer's machine in it. A copy written for another account, or read while signed out, is the
 * defaults: a copy kept for the whole installation must never turn one account's experiments on for another (the
 * desktop app keeps the same rule for its own). A file that is missing or cannot be read is the defaults too, never a
 * refusal to work.
 */
import { chmodSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { readAuthSession, type AuthSession } from './authSession.js'

export interface AgentSettings {
  /** Agents may start, wait for and close harnesses of their own, and are told how as they start. */
  agentsStartAgents: boolean
  /** A harness another agent started adds a line to the pull requests it opens (lib/agentAttribution.ts). Read at
   *  each launch of one, so a harness running when it is turned off keeps its line until it restarts. */
  pullRequestLine: boolean
  /** Agents in the same tab may message each other (`harness send`, messages/service.ts). It replaced each tab's own
   *  switch, a chat icon beside its × that was easy to hit by mistake (owner, 2026-10-12). */
  agentMessages: boolean
  /** Agent Messages does not tell a shared tab's other accounts a one-line summary of what each harness does. Stored
   *  inverted, as the account's experiment is (backend lib/experimentalSettings.ts): every one of them is "off unless
   *  true", and sharing the summary is the default. */
  agentMessagesHideSummary: boolean
  /** An agent may give more work to a harness it started (`harness tell`, messages/tell.ts), with no tab and whether
   *  Agent Messages are on or not. A switch of its own, off by default: the owner ruled that a harness another started
   *  gets no exception from Agent Messages (2026-10-11), so this one-way order from the starter is the person's to
   *  allow, not a side effect of starting. */
  agentsTellAgents: boolean
  /** A program acting for the person (the lamp's `lamp-tasks`, not an agent) may give more work to an idle harness of
   *  theirs in a pane (`harness reply`, messages/replyLocal.ts), as the person could by typing in Harness. Off by
   *  default, and not `agents-tell-agents`, which is about agents (#1628). */
  programsReply: boolean
}

export const AGENT_SETTINGS_DEFAULTS: AgentSettings = { agentsStartAgents: false, pullRequestLine: false, agentMessages: false, agentMessagesHideSummary: false, agentsTellAgents: false, programsReply: false }

/** Each setting's name in `harness settings`, and its key. */
export const AGENT_SETTING_NAMES: Record<string, keyof AgentSettings> = { 'agents-start-agents': 'agentsStartAgents', 'agents-tell-agents': 'agentsTellAgents', 'pull-request-line': 'pullRequestLine', 'agent-messages': 'agentMessages', 'agent-messages-hide-summary': 'agentMessagesHideSummary', 'programs-reply': 'programsReply' }

/** Each setting's account experiment, as the backend names it (lib/experimentalSettings.ts `experimentalFeatures`). */
export const AGENT_SETTING_EXPERIMENTS: Record<keyof AgentSettings, string> = { agentsStartAgents: 'agents_start_agents', pullRequestLine: 'agent_pull_request_line', agentMessages: 'agent_messages', agentMessagesHideSummary: 'agent_messages_hide_summary', agentsTellAgents: 'agents_tell_agents', programsReply: 'programs_reply' }

/** The flag an agent adds to `harness settings <name> on` once the person said yes to it (agentClient/settings.ts). */
export const PERSON_SAID_YES = '--person-said-yes'

/** What an agent asks the person before it turns each setting on: one question they can answer yes or no. */
export const AGENT_SETTING_QUESTIONS: Record<keyof AgentSettings, string> = {
  agentsStartAgents: 'May I start other agents (Claude Code, Codex) in harnesses of their own, for work that can run beside mine?',
  agentsTellAgents: 'May I give more work to the harnesses I started, in the conversations they already have?',
  pullRequestLine: 'May a harness another agent started say so in the pull requests it opens?',
  agentMessages: 'May agents in the same tab message each other?',
  agentMessagesHideSummary: 'May Harness share a one-line summary of what your harnesses do with the people in your shared tabs?',
  programsReply: 'May programs that act for you, like your lamp, give more work to a harness of yours that is idle, as you could by typing to it?',
}

/**
 * What an agent refused by a setting that is off is told to do: ask the person with its own tool for questions, and turn
 * the setting on only after their yes. People do not run `harness settings` themselves: they ask their agent for the work,
 * and a refusal that sent them to a terminal, or to a Settings switch the app does not show, left the work undone
 * (2026-10-26). Harness takes the agent's word for the yes (the `--person-said-yes` flag), so the words say plainly that
 * the person answers it, never the agent. [otherwise] is what to do if they say no. [value] is the one that grants:
 * `off` for the summary switch, which is stored inverted.
 */
export function askThePersonFirst(name: string, otherwise: string, value: 'on' | 'off' = 'on'): string {
  const key = AGENT_SETTING_NAMES[name]
  const question = key ? AGENT_SETTING_QUESTIONS[key] : `May I turn ${value} ${name}?`
  return `${name} is ${value === 'on' ? 'off' : 'on'}. Ask the person, with your tool for asking them (Claude Code: AskUserQuestion; Codex: request_user_input), `
    + `or in your reply, and wait for their answer: "${question}" Only if they say yes, run \`harness settings ${name} ${value} ${PERSON_SAID_YES}\` `
    + `(through MCP: harness_settings with person_said_yes), then try again. Never answer it for them. If they say no: ${otherwise}`
}

/** Whom a copy is for: the account, and this computer's machine in it. A machine is one account's, so a sign-in to
 *  another account on this computer has another. */
export interface AgentSettingsOwner { accountId: string; machineId: string }

export const agentSettingsPath = (dataDir: string): string => join(dataDir, 'agent-settings.json')

/** Whether a copy kept for [owner] is this sign-in's: the same machine, and the same account where the session knows
 *  its account (`signInAcct`, recorded after a sign-in by hand). */
export const ownsAgentSettings = (owner: AgentSettingsOwner, session: AuthSession | null): boolean =>
  !!session?.machineId && owner.machineId === session.machineId && (!session.signInAcct || owner.accountId === session.signInAcct)

/** The settings for whoever is signed in here now ([session], read from its file unless given). */
export function readAgentSettings(dataDir: string, session: AuthSession | null = readAuthSession()): AgentSettings {
  try {
    const saved = JSON.parse(readFileSync(agentSettingsPath(dataDir), 'utf8')) as Record<string, unknown>
    // A copy from before they were the account's names no one: Settings ▸ Agents wrote it, for this computer alone.
    if (typeof saved.accountId !== 'string' || typeof saved.machineId !== 'string'
      || !ownsAgentSettings({ accountId: saved.accountId, machineId: saved.machineId }, session)) return { ...AGENT_SETTINGS_DEFAULTS }
    return Object.fromEntries(Object.entries(AGENT_SETTINGS_DEFAULTS)
      .map(([key, fallback]) => [key, typeof saved[key] === 'boolean' ? saved[key] : fallback])) as unknown as AgentSettings
  } catch {
    return { ...AGENT_SETTINGS_DEFAULTS }
  }
}

/** The settings an answer of `GET` or `PATCH /api/experimental-settings` gives, and whose; null for any other
 *  answer. An experiment the backend does not name (one from before them) is off. */
export function agentSettingsFromAnswer(answer: { status: number; body: Record<string, unknown> }): { accountId: string; settings: AgentSettings } | null {
  const data = answer.status === 200 && answer.body.success === true ? answer.body.data as { accountId?: unknown; features?: unknown } | null | undefined : null
  if (typeof data?.accountId !== 'string' || !data.accountId || !data.features || typeof data.features !== 'object') return null
  const features = data.features as Record<string, unknown>
  return {
    accountId: data.accountId,
    settings: Object.fromEntries(Object.entries(AGENT_SETTING_EXPERIMENTS).map(([key, feature]) => [key, features[feature] === true])) as unknown as AgentSettings,
  }
}

/** Keeps [settings] for [owner]: written whole and renamed into place, so a reader never sees half a file. The core's
 *  sync alone calls it. */
export function saveAgentSettings(dataDir: string, owner: AgentSettingsOwner, settings: AgentSettings): void {
  const path = agentSettingsPath(dataDir)
  const temporary = `${path}.${process.pid}.tmp`
  writeFileSync(temporary, `${JSON.stringify({ version: 2, accountId: owner.accountId, machineId: owner.machineId, ...settings })}\n`, { mode: 0o600 })
  chmodSync(temporary, 0o600)
  renameSync(temporary, path)
}