@sonetto/atom

Typed agent loop core for custom harnesses.

Atom provides tools, abilities, ordered conversation state, semantic events, cancellation, async iteration, and manual stepping.

Install

pnpm add @sonetto/atom

Usage

import { atom, tool } from '@sonetto/atom'

const echo = tool(
  {
    about: 'Echo a string.',
  },
  async (value: string) => value,
)

const run = atom({
  tools: { echo },
  model({ turns }) {
    if (!turns.some((turn) => turn.type === 'result')) {
      return { type: 'tool', name: 'echo', input: 'hello' }
    }

    return 'done'
  },
})

const execution = run('start')

for await (const event of execution) {
  if (event.type === 'tool') console.log(event.name, event.input)
}

console.log(await execution.result)

Manual stepping uses the same execution object:

const execution = run('start', { mode: 'manual' })
const event = await execution.step()

License

Copyright © 2026 Yu (Alpha You)

Open sourced under MIT license.