feat(agent): add coreutils (echo, cat, ls, pwd, wc, head, tail, grep, true, false)

Each command is a Command function using the CmdContext / AsyncIterable
protocol, so they compose with the runtime's pipe engine. registerCoreutils()
installs all of them on a CommandRegistry.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: snomiao

src/agent/shell/commands/coreutils.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest'
+
+import { CommandRegistryImpl } from '../runtime'
+import type { CmdContext } from '../types'
+import { collect, emptyIter, stringIter } from '../types'
+import { MemoryVFS } from '../vfs/memory'
+import { coreutils, registerCoreutils } from './coreutils'
+
+function baseCtx(
+  argv: string[],
+  stdin: AsyncIterable<string> = emptyIter(),
+  vfs = new MemoryVFS()
+): CmdContext {
+  return {
+    argv,
+    stdin,
+    env: new Map(),
+    cwd: '/',
+    vfs,
+    signal: new AbortController().signal
+  }
+}
+
+describe('coreutils', () => {
+  it('echo joins args with space', async () => {
+    const r = await coreutils.echo(baseCtx(['echo', 'hello', 'world']))
+    expect(await collect(r.stdout)).toBe('hello world\n')
+  })
+
+  it('echo -n omits newline', async () => {
+    const r = await coreutils.echo(baseCtx(['echo', '-n', 'hi']))
+    expect(await collect(r.stdout)).toBe('hi')
+  })
+
+  it('cat reads file', async () => {
+    const fs = new MemoryVFS()
+    await fs.write('/f', 'contents')
+    const r = await coreutils.cat(baseCtx(['cat', '/f'], emptyIter(), fs))
+    expect(await collect(r.stdout)).toBe('contents')
+  })
+
+  it('cat passes through stdin with no args', async () => {
+    const r = await coreutils.cat(baseCtx(['cat'], stringIter('passed\n')))
+    expect(await collect(r.stdout)).toBe('passed\n')
+  })
+
+  it('ls lists sorted entries', async () => {
+    const fs = new MemoryVFS()
+    await fs.write('/b', '')
+    await fs.write('/a', '')
+    await fs.write('/sub/x', '')
+    const r = await coreutils.ls(baseCtx(['ls', '/'], emptyIter(), fs))
+    expect(await collect(r.stdout)).toBe('a\nb\nsub/\n')
+  })
+
+  it('pwd emits cwd', async () => {
+    const r = await coreutils.pwd(baseCtx(['pwd']))
+    expect(await collect(r.stdout)).toBe('/\n')
+  })
+
+  it('wc counts lines, words, bytes', async () => {
+    const r = await coreutils.wc(baseCtx(['wc'], stringIter('a\nb\nc\n')))
+    expect(await collect(r.stdout)).toBe('3 3 6\n')
+  })
+
+  it('head -n 2 keeps first 2', async () => {
+    const r = await coreutils.head(
+      baseCtx(['head', '-n', '2'], stringIter('1\n2\n3\n4\n'))
+    )
+    expect(await collect(r.stdout)).toBe('1\n2\n')
+  })
+
+  it('tail -n 2 keeps last 2', async () => {
+    const r = await coreutils.tail(
+      baseCtx(['tail', '-n', '2'], stringIter('1\n2\n3\n4\n'))
+    )
+    expect(await collect(r.stdout)).toBe('3\n4\n')
+  })
+
+  it('grep filters', async () => {
+    const r = await coreutils.grep(
+      baseCtx(['grep', 'foo'], stringIter('foo\nbar\nfood\n'))
+    )
+    expect(await collect(r.stdout)).toBe('foo\nfood\n')
+  })
+
+  it('true exits 0, false exits 1', async () => {
+    expect((await coreutils.true(baseCtx(['true']))).exitCode).toBe(0)
+    expect((await coreutils.false(baseCtx(['false']))).exitCode).toBe(1)
+  })
+
+  it('registerCoreutils registers all commands', () => {
+    const reg = new CommandRegistryImpl()
+    registerCoreutils(reg)
+    expect(reg.list()).toEqual(
+      [
+        'cat',
+        'echo',
+        'false',
+        'grep',
+        'head',
+        'ls',
+        'pwd',
+        'tail',
+        'true',
+        'wc'
+      ].sort()
+    )
+  })
+})

src/agent/shell/commands/coreutils.ts

@@ -0,0 +1,152 @@
+import type { CmdContext, CmdResult, Command, CommandRegistry } from '../types'
+import { collect, emptyIter, lines, stringIter } from '../types'
+
+function ok(stdout: AsyncIterable<string>, exitCode = 0): CmdResult {
+  return { stdout, exitCode }
+}
+
+function err(message: string, exitCode = 2): CmdResult {
+  return { stdout: emptyIter(), exitCode, stderr: message }
+}
+
+const echo: Command = async (ctx) => {
+  const args = ctx.argv.slice(1)
+  let newline = true
+  if (args[0] === '-n') {
+    newline = false
+    args.shift()
+  }
+  const text = args.join(' ') + (newline ? '\n' : '')
+  return ok(stringIter(text))
+}
+
+const cat: Command = async (ctx) => {
+  const paths = ctx.argv.slice(1)
+  if (paths.length === 0) return ok(ctx.stdin)
+  async function* gen(): AsyncIterable<string> {
+    for (const p of paths) {
+      yield await ctx.vfs.read(p)
+    }
+  }
+  return ok(gen())
+}
+
+const ls: Command = async (ctx) => {
+  const path = ctx.argv[1] ?? ctx.cwd
+  const entries = await ctx.vfs.list(path)
+  const out =
+    entries.map((e) => (e.type === 'dir' ? e.name + '/' : e.name)).join('\n') +
+    (entries.length > 0 ? '\n' : '')
+  return ok(stringIter(out))
+}
+
+const pwd: Command = async (ctx) => ok(stringIter(ctx.cwd + '\n'))
+
+const wc: Command = async (ctx) => {
+  const data = await collect(ctx.stdin)
+  const bytes = data.length
+  const lineCount =
+    data === '' ? 0 : data.split('\n').length - (data.endsWith('\n') ? 1 : 0)
+  const words = data.split(/\s+/).filter((w) => w.length > 0).length
+  return ok(stringIter(`${lineCount} ${words} ${bytes}\n`))
+}
+
+function parseNFlag(
+  argv: string[],
+  defaultN: number
+): { n: number; rest: string[] } {
+  const rest = argv.slice(1)
+  let n = defaultN
+  if (rest[0] === '-n') {
+    const parsed = Number(rest[1])
+    if (!Number.isFinite(parsed)) throw new Error('invalid -n value')
+    n = parsed
+    rest.splice(0, 2)
+  } else if (rest[0]?.startsWith('-n')) {
+    const parsed = Number(rest[0].slice(2))
+    if (!Number.isFinite(parsed)) throw new Error('invalid -n value')
+    n = parsed
+    rest.shift()
+  }
+  return { n, rest }
+}
+
+const head: Command = async (ctx) => {
+  let n: number
+  try {
+    ;({ n } = parseNFlag(ctx.argv, 10))
+  } catch (e) {
+    return err('usage: head [-n N]')
+  }
+  async function* gen(): AsyncIterable<string> {
+    let i = 0
+    for await (const line of lines(ctx.stdin)) {
+      if (i >= n) break
+      yield line + '\n'
+      i++
+    }
+  }
+  return ok(gen())
+}
+
+const tail: Command = async (ctx) => {
+  let n: number
+  try {
+    ;({ n } = parseNFlag(ctx.argv, 10))
+  } catch (e) {
+    return err('usage: tail [-n N]')
+  }
+  const buf: string[] = []
+  for await (const line of lines(ctx.stdin)) {
+    buf.push(line)
+    if (buf.length > n) buf.shift()
+  }
+  const out = buf.length > 0 ? buf.join('\n') + '\n' : ''
+  return ok(stringIter(out))
+}
+
+const grep: Command = async (ctx) => {
+  const pattern = ctx.argv[1]
+  if (!pattern) return err('usage: grep <pattern>')
+  const re = new RegExp(pattern)
+  async function* gen(): AsyncIterable<string> {
+    let matched = false
+    for await (const line of lines(ctx.stdin)) {
+      if (re.test(line)) {
+        yield line + '\n'
+        matched = true
+      }
+    }
+    void matched
+  }
+  return ok(gen())
+}
+
+const trueCmd: Command = async () => ok(emptyIter(), 0)
+const falseCmd: Command = async () => ok(emptyIter(), 1)
+
+export function registerCoreutils(registry: CommandRegistry): void {
+  registry.register('echo', echo)
+  registry.register('cat', cat)
+  registry.register('ls', ls)
+  registry.register('pwd', pwd)
+  registry.register('wc', wc)
+  registry.register('head', head)
+  registry.register('tail', tail)
+  registry.register('grep', grep)
+  registry.register('true', trueCmd)
+  registry.register('false', falseCmd)
+}
+
+export const coreutils = {
+  echo,
+  cat,
+  ls,
+  pwd,
+  wc,
+  head,
+  tail,
+  grep,
+  true: trueCmd,
+  false: falseCmd
+} satisfies Record<string, (ctx: CmdContext) => Promise<CmdResult>>