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.

11.2 KB
Raw Blame
import { join as hookPath } from 'node:path'
import { env as hookEnvironment } from '../../config/env.js'
import { PLUGIN_FETCH } from '../kit/pluginFetch.js'
/**
 * What the core knows of Amp without loading its code: declared data, read by the kit
 * (docs/design/2026-10-08-other-engines-out-of-core.md). It imports no Amp interpreter.
 */
export const contract = {
  /** Its approval rows are stacked and numbered by nothing: a row is reached by walking Down from the first
   *  (askQuestion.ts), and `kit/questionPane.ts` `walkKeys` turns that into keys. */
  questionWalk: 'down',
} as const

/** Native source runs in the engine process; the daemon only renders and installs these bytes. */
export const AMP_PLUGIN = {
  file: hookPath(hookEnvironment.AMP_PLUGIN_DIR, 'launcher-register.ts'),
  template: [
`// session-register — auto-installed by the machine adapter. Binds this Amp thread to the local
// machine daemon (127.0.0.1:`,
{ argument: 'port' },
`) and writes the transcript the daemon tails, because Amp keeps none
// on disk. No-op outside tmux.
import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
import { join } from 'node:path'

export const description = 'Mirrors this Amp thread to the machine adapter (web + device)'

const SESSIONS_DIR = `,
JSON.stringify(hookEnvironment.AMP_SESSIONS_DIR),
`

`,
...PLUGIN_FETCH,
`export default function (amp: any) {
  const pane = process.env.TMUX_PANE
  if (!pane) return

  // NOT \`process.cwd()\`: Bun runs a plugin with the PLUGIN's directory as its cwd, so that reports
  // \`<project>/.amp/plugins\` (measured). \`PWD\` is inherited from the shell that launched plain Amp.
  const workdir = process.env.PWD || process.cwd()

  const emitted = new Set()
  // Turn ids already opened/closed. Amp re-dispatches a message it could not deliver, firing agent.start
  // a SECOND time for the same message id (measured: two identical turn_start records 61s apart, then a
  // turn_end 'done' and a turn_end 'error' for the one turn). Written straight through, that is two turns
  // on web and device and two user bubbles in history.
  const turnsStarted = new Set()
  const turnsEnded = new Set()
  // Tool ids already written, so a tool seen BOTH as an event and as a message block is written once.
  const toolCalls = new Set()
  const toolResults = new Set()
  let registered = false
  let file = ''
  let seeded = false

  const line = (record: any) => {
    try {
      mkdirSync(SESSIONS_DIR, { recursive: true, mode: 0o700 })
      appendFileSync(file, JSON.stringify(record) + '\\n')
    } catch {}
  }

  const open = (threadId: string) => {
    if (file) return
    file = join(SESSIONS_DIR, threadId + '.jsonl')
    // \`cwd\` on the first line is what lets the daemon re-find this session by directory after a restart,
    // the same way it reads claude's and pi's transcripts. It must be a top-level string field.
    line({ t: 'session', threadId, cwd: workdir, at: Date.now() })
  }

  const register = async (threadId: string) => {
    open(threadId)
    if (registered || !existsSync(file)) return
    try {
      const token = readFileSync(`,
{ argument: 'credential' },
`, 'utf8').trim()
      if (!token) return
      const res = await harnessFetch('http://127.0.0.1:`,
{ argument: 'port' },
`/api/hook/session-start', {
        method: 'POST',
        headers: { 'content-type': 'application/json', 'x-harness-hook-token': token },
        body: JSON.stringify({
          engine: 'amp',
          pluginVersion: `,
{ argument: 'version' },
`,
          sessionId: threadId,
          transcriptPath: file,
          cwd: workdir,
          tmuxPane: pane,
          callerPid: process.pid,
          runtimeHints: [
            ...(pane ? [{ backend: 'tmux', paneId: pane }] : []),
          ],
        }),
      })
      if (res.ok) registered = true
    } catch {}
  }

  const resultId = (block: any) => String(block.toolUseID || block.tool_use_id || '')

  /**
   * Write everything in the thread that has not been written yet.
   *
   * This reads message BLOCKS rather than events, because the events do not cover the thread:
   *
   *   - no event carries assistant text at all, and
   *   - \`tool.call\`/\`tool.result\` only fire for tools the CLIENT executes. MEASURED: a \`web_search\`
   *     turn produced no tool event and no tool lease in Amp's own log, yet the message plainly held a
   *     \`tool_use\` block — Amp runs that tool on its server. Skipping blocks meant a search rendered as
   *     nothing at all on web and device while the pane showed "Explored 1 search".
   *
   * \`seed\` marks what already exists WITHOUT writing it, for a thread that is being resumed: those
   * messages belong to earlier turns, and replaying them made a fresh turn open with an old answer in it.
   */
  const drain = async (ctx: any) => {
    let messages: any[] = []
    try { messages = await ctx.thread.messages({ from: 'end', limit: 20 }) } catch { return }
    // The FIRST drain of this plugin instance only claims what it finds; it writes nothing. That covers
    // both ways a plugin meets a thread that already has messages: a resumed thread, and a plugin reload
    // (Amp loads a plugin ONCE per process, so reload is how a running pane picks up a new build). Without
    // it, the next prompt replayed the whole recent history as if it had just happened.
    const seed = !seeded
    seeded = true
    // The seed pass would swallow the very prompt the turn needs to open on. Measured: \`session.start\`
    // does NOT fire when Amp launches — it fires on the first submit, and by then the thread already
    // holds one \`user\` message. So the seed has to tell history from the live prompt, and the test is
    // whether anything answered it: the LAST user text block with no assistant message after it is
    // waiting, not past. On a resumed thread the last message is an assistant one, so nothing opens.
    let liveUserId = ''
    for (const message of messages) {
      if (message.role === 'assistant') { liveUserId = ''; continue }
      const parts = Array.isArray(message.content) ? message.content : []
      const hasText = parts.some((b: any) => b && b.type === 'text' && typeof b.text === 'string' && b.text)
      if (hasText) liveUserId = String(message.id)
    }
    for (const message of messages) {
      const blocks = Array.isArray(message.content) ? message.content : []
      for (let i = 0; i < blocks.length; i++) {
        const block = blocks[i]
        if (!block) continue
        if (block.type === 'text' || block.type === 'thinking') {
          const key = String(message.id) + '#' + i
          if (emitted.has(key)) continue
          const text = typeof block.text === 'string' ? block.text : block.thinking
          if (typeof text !== 'string' || !text) continue
          emitted.add(key)
          // A user TEXT block opens the turn.
          //
          // Amp used to announce that with an \`agent.start\` event, and the handler below wrote
          // \`turn_start\` from it. That event no longer fires — probed with a plugin that registered for
          // sixteen candidate names on amp 0.0.1786681855 and saw only \`session.start\`, \`tool.call\`,
          // \`tool.result\` and \`agent.end\`. The prompt now reaches a plugin no earlier than
          // \`agent.end\`, which is the END of the turn, far too late to open one.
          //
          // So it is taken from the thread instead, where drain was already reading it and dropping it:
          // measured at the first \`tool.call\` of a turn, \`messages()\` already returns the prompt, oldest
          // first. Without this the turn opens with an empty question on web and device, and the recap
          // loses what was asked.
          //
          // Only a TEXT block qualifies: a tool_result is also carried on a \`user\` message, so matching
          // the role alone would open a turn on every tool that returned.
          if (message.role !== 'assistant') {
            const turnId = String(message.id)
            if (turnsStarted.has(turnId)) continue
            turnsStarted.add(turnId)
            if (!seed || turnId === liveUserId) line({ t: 'turn_start', id: turnId, message: text, at: Date.now() })
            continue
          }
          if (!seed) line({ t: block.type, id: message.id, i, text })
        } else if (block.type === 'tool_use') {
          const id = String(block.id || '')
          if (!id || toolCalls.has(id)) continue
          toolCalls.add(id)
          if (!seed) line({ t: 'tool_call', id, tool: block.name, input: block.input })
        } else if (block.type === 'tool_result') {
          const id = resultId(block)
          if (!id || toolResults.has(id)) continue
          toolResults.add(id)
          // A server-run tool puts its payload under \`run\`; a client-run one under \`content\`/\`output\`.
          if (!seed) line({ t: 'tool_result', id, status: 'done', output: block.run ?? block.content ?? block.output })
        }
      }
    }
  }

  amp.on('session.start', async (event: any, ctx: any) => {
    await register(event.thread.id)
    await drain(ctx)
  })

  amp.on('agent.start', async (event: any, ctx: any) => {
    await register(event.thread.id)
    const id = String(event.id)
    if (!turnsStarted.has(id)) {
      turnsStarted.add(id)
      line({ t: 'turn_start', id: event.id, message: event.message, at: Date.now() })
    }
    await drain(ctx)
  })

  amp.on('tool.call', async (event: any, ctx: any) => {
    await register(event.thread.id)
    // CLAIM THE ID FIRST. \`drain\` runs before this card so a message's prose lands ahead of the tool it
    // called — but by then the tool_use block for THIS tool is already in the thread, so draining without
    // claiming wrote the card twice (measured: one Task turn produced two identical \`skill\` cards).
    toolCalls.add(String(event.toolUseID))
    await drain(ctx)
    line({ t: 'tool_call', id: event.toolUseID, tool: event.tool, input: event.input })
  })

  amp.on('tool.result', async (event: any, ctx: any) => {
    // Same rule as tool.call: claim before draining.
    toolResults.add(String(event.toolUseID))
    line({
      t: 'tool_result',
      id: event.toolUseID,
      tool: event.tool,
      status: event.status,
      output: event.output,
    })
    await drain(ctx)
  })

  amp.on('agent.end', async (event: any, ctx: any) => {
    await drain(ctx)
    // \`message\` is the prompt that STARTED this turn, and agent.end carries it even when
    // agent.start never fired (a prompt queued while Amp was connecting). Recording it here is what
    // lets history still show what was asked — see the replay branch in the normalizer.
    const id = String(event.id)
    if (turnsEnded.has(id)) return
    turnsEnded.add(id)
    line({ t: 'turn_end', id: event.id, status: event.status, message: event.message, at: Date.now() })
  })
}
`
],
  directories: [{ path: hookEnvironment.AMP_SESSIONS_DIR, mode: 0o700 }],
  messages: {
  "current": "[hooks] Amp plugin already installed",
  "installed": "[hooks] installed Amp plugin → {file}",
  "after": [
    "[hooks] a NEW amp session picks this up automatically; for one already open, run",
    "[hooks]   ctrl+o → 'plugins: reload'   (or restart that pane)"
  ],
  "failed": "[hooks] failed to write Amp plugin:"
},
} as const satisfies import('../kit/nativePlugin.js').NativePlugin