@excitedjs/tm 1.1.0

package/src/verbs/spawn.ts

@@ -0,0 +1,81 @@
+/**
+ * `tm spawn <name> --engine <k>` — atomic teammate spawn. Decision
+ * multi-engine-tui-architecture §"Round-trips are atomic by default" makes a `--prompt` an
+ * atomic first turn; `--no-wait` is gone. Engine selection is the
+ * explicit `--engine` flag (decision codex-engine-flag §1, carried forward).
+ *
+ * Phase 1 lands the skeleton: parse a `SpawnRequest`, look the engine
+ * up in the registry, dispatch. With the Phase 1 empty registry, the
+ * verb falls through to `noEngineRegistered()`; Phase 2 registers the
+ * concrete Claude / Codex engines and the spawn round-trip becomes
+ * live.
+ */
+
+import { noEngineRegistered } from './format'
+import type {
+  EngineKind,
+  SpawnRequest,
+  SpawnResult,
+  TeammateName,
+} from '../engines/types'
+import type { TmResult } from '../tm'
+import type { VerbContext } from './context'
+
+export interface SpawnArgs {
+  readonly name: TeammateName
+  readonly engine: EngineKind
+  readonly repo: string
+  readonly cwd: string
+  readonly worktreeSlug: string | null
+  readonly resumeCheckpoint: string | null
+  readonly prompt: string | null
+  readonly timeoutMs: number | null
+  readonly displayName: string | null
+}
+
+export async function spawnVerb(args: SpawnArgs, ctx: VerbContext): Promise<TmResult> {
+  const engine = ctx.engines.get(args.engine)
+  if (engine === undefined) return noEngineRegistered()
+  if (engine.kind !== 'claude' && args.resumeCheckpoint !== null) {
+    return {
+      code: 1,
+      stdout: '',
+      stderr: 'tm: tm spawn: --resume is not supported for codex teammates\n',
+    }
+  }
+
+  const req: SpawnRequest = {
+    name: args.name,
+    repo: args.repo,
+    cwd: args.cwd,
+    worktreeSlug: args.worktreeSlug,
+    resumeCheckpoint: args.resumeCheckpoint,
+    prompt: args.prompt,
+    timeoutMs: args.timeoutMs,
+    displayName: args.displayName,
+  }
+  const result: SpawnResult = await engine.spawn(req, ctx.engineContext)
+  if (result.tmResult !== undefined) {
+    return result.tmResult
+  }
+
+  switch (result.kind) {
+    case 'spawned':
+      return { code: 0, stdout: `spawned: ${result.name}\n`, stderr: '' }
+    case 'already-exists':
+      if (args.engine === 'codex') {
+        return {
+          code: 1,
+          stdout: '',
+          stderr: `tm: codex teammate '${args.name}' already exists (engine=${result.existingEngine})\n`,
+        }
+      }
+      return {
+        code: 1,
+        stdout: '',
+        stderr: `tm: '${args.name}' already exists as a ${result.existingEngine} teammate\n`,
+      }
+    case 'failed':
+      return { code: 1, stdout: '', stderr: `tm: ${result.message}\n` }
+  }
+}

package/src/verbs/states.ts

@@ -0,0 +1,74 @@
+/**
+ * `tm states` — rich fleet listing.
+ *
+ * Each row carries seven cells:
+ * `NAME REPO WORKTREE ENGINE STATE LAST PREVIEW`. The identity cells
+ * (NAME / REPO / WORKTREE / ENGINE / STATE) come from the listing
+ * itself; the runtime cells (LAST / PREVIEW) come from the
+ * engine-private `extras` map. The combined `state` column
+ * collapses the legacy `BUSY` cell — `state === 'busy'` is the only
+ * way to read "the teammate is mid-turn", same signal, more readable.
+ *
+ * The verb owns the column alignment via `runColumn` so the table
+ * reads the same way the legacy `tm states | column -t` did.
+ */
+
+import type { TmResult } from '../tm'
+import { noEngineRegistered } from './format'
+import type { VerbContext } from './context'
+
+type StatesRow = readonly [
+  string, string, string, string,
+  string, string, string,
+]
+
+const HEADER: StatesRow = [
+  'NAME',
+  'REPO',
+  'WORKTREE',
+  'ENGINE',
+  'STATE',
+  'LAST',
+  'PREVIEW',
+]
+
+/** Pull a string-typed extra; missing or non-string falls back to `-`. */
+function cell(extras: Readonly<Record<string, string>>, key: string): string {
+  const value = extras[key]
+  return typeof value === 'string' && value.length > 0 ? value : '-'
+}
+
+/** Last path segment, or `-` when the path is empty / "/". */
+function repoLeaf(path: string): string {
+  if (path.length === 0) return '-'
+  const trimmed = path.replace(/\/+$/, '')
+  const slash = trimmed.lastIndexOf('/')
+  const leaf = slash >= 0 ? trimmed.slice(slash + 1) : trimmed
+  return leaf.length === 0 ? '-' : leaf
+}
+
+export async function statesVerb(ctx: VerbContext): Promise<TmResult> {
+  const engines = ctx.engines.registered()
+  if (engines.length === 0) return noEngineRegistered()
+
+  const listings = (
+    await Promise.all(engines.map((engine) => engine.list(ctx.engineContext)))
+  ).flat()
+
+  if (listings.length === 0) return { code: 0, stdout: '(no teammate sessions)\n', stderr: '' }
+
+  const rows: StatesRow[] = [
+    HEADER,
+    ...listings.map<StatesRow>((row) => [
+      row.name,
+      repoLeaf(row.repo),
+      row.worktreeSlug ?? '-',
+      row.engine,
+      row.state,
+      cell(row.extras, 'last'),
+      cell(row.extras, 'preview'),
+    ]),
+  ]
+
+  return ctx.runColumn(`${rows.map((row) => row.join('\t')).join('\n')}\n`)
+}

package/src/verbs/status.ts

@@ -0,0 +1,26 @@
+/**
+ * `tm status <name>` — per-teammate snapshot. Decision multi-engine-tui-architecture amend
+ * lines 157-161 fix the default impl: resolve the teammate name
+ * through the router, hand the engine the request, format the result.
+ * A teammate that has no tmux session (a Codex daemon teammate)
+ * resolves through the same path; the verb has no tmux knowledge.
+ */
+
+import { formatStatus, teammateNotFound } from './format'
+import type { TeammateName } from '../engines/types'
+import type { TmResult } from '../tm'
+import type { VerbContext } from './context'
+
+export async function statusVerb(
+  name: TeammateName,
+  ctx: VerbContext,
+  options: { lines: number | null } = { lines: null },
+): Promise<TmResult> {
+  const resolved = await ctx.router.resolve(name)
+  if (resolved === null) return teammateNotFound(name)
+  const status = await resolved.engine.status(
+    { name, lines: options.lines },
+    ctx.engineContext,
+  )
+  return formatStatus(status)
+}

package/src/verbs/wait.ts

@@ -0,0 +1,40 @@
+/**
+ * `tm wait <name>` — the recovery seam. Decision multi-engine-tui-architecture §"Round-trips
+ * are atomic by default" keeps this verb for the case where a previous
+ * `send` / `spawn` aborted before reading the reply; a follow-up wait
+ * picks up the next completion. Not the default path.
+ */
+
+import { formatTurn } from './format'
+import type { TeammateName, WaitRequest } from '../engines/types'
+import type { TmResult } from '../tm'
+import type { VerbContext } from './context'
+import { resolveTargetEngine } from './resolve'
+
+export interface WaitArgs {
+  readonly name: TeammateName
+  readonly recoverFor: string | null
+  readonly timeoutMs: number | null
+  readonly fresh: boolean
+  readonly paneQuiet: boolean
+}
+
+export async function waitVerb(args: WaitArgs, ctx: VerbContext): Promise<TmResult> {
+  const engine = await resolveTargetEngine(args.name, ctx)
+  if ('code' in engine) return engine
+  if (args.fresh && engine.kind !== 'claude') {
+    return { code: 1, stdout: '', stderr: 'tm: tm wait: --fresh is not supported for codex teammates\n' }
+  }
+  if (args.paneQuiet && engine.kind !== 'claude') {
+    return { code: 1, stdout: '', stderr: 'tm: tm wait: --pane-quiet is not supported for codex teammates\n' }
+  }
+
+  const req: WaitRequest = {
+    name: args.name,
+    recoverFor: args.recoverFor,
+    timeoutMs: args.timeoutMs,
+    fresh: args.fresh,
+    paneQuiet: args.paneQuiet,
+  }
+  return formatTurn(await engine.wait(req, ctx.engineContext))
+}

package/src/verbs.ts

@@ -0,0 +1,56 @@
+/**
+ * The catalog of `tm` verbs the core re-exposes as MCP tools.
+ *
+ * The core exposes the *whole* `tm` verb set — the migration's exit gate is
+ * "reproduces today's `tm` behavior for every verb", so no verb is carved
+ * out. Each verb becomes one MCP tool; `core.ts` runs it natively (`native.ts`)
+ * or shells out to `tm`, per verb, as the strangler migration moves verbs
+ * across. The `help` verb is intentionally absent: the MCP tool schemas are
+ * themselves the dispatcher-facing help surface, so a `tm help` passthrough
+ * would be redundant.
+ *
+ * The `summary` strings are short, lifted from `tm --help`. Rich per-argument
+ * schemas — "the MCP tool descriptions become the new `tm --help`" — are a
+ * Phase D task; until then a verb tool forwards an opaque argument vector.
+ * The one exception is the registry-affecting verbs (`registry !== 'none'`):
+ * their tools take a required structured `repo` field, because the core keys
+ * the registry on the teammate identity and must read it as data, not parse
+ * it back out of the argument vector (see `core.ts`).
+ */
+
+/** One `tm` verb re-exposed as an MCP tool. */
+export interface VerbSpec {
+  /** The verb name — also the MCP tool name. */
+  name: string
+  /** One-line description, shown to the dispatcher in the MCP tool list. */
+  summary: string
+  /**
+   * How invoking this verb changes the teammate registry. `spawn`/`resume`
+   * record a teammate, `kill` removes one; every other verb leaves the
+   * teammate set unchanged. The core applies this after a successful
+   * shell-out (see `core.ts`).
+   */
+  registry: 'record' | 'remove' | 'none'
+}
+
+/** Every `tm` verb the core fronts, in the order `tm --help` lists them. */
+export const TM_VERBS: readonly VerbSpec[] = [
+  { name: 'send', summary: 'Atomic round-trip: send a prompt to a teammate, wait, print the reply.', registry: 'none' },
+  { name: 'spawn', summary: 'Launch a teammate; with --prompt, also bootstrap it atomically.', registry: 'record' },
+  { name: 'wait', summary: "Wait for a teammate's next Stop and print the reply.", registry: 'none' },
+  { name: 'compact', summary: 'Run /compact on a teammate and verify it completed.', registry: 'none' },
+  { name: 'resume', summary: 'Resume a prior conversation for a teammate.', registry: 'record' },
+  { name: 'last', summary: "Reprint a teammate's last-turn reply.", registry: 'none' },
+  { name: 'kill', summary: "Kill a teammate's tmux session.", registry: 'remove' },
+  { name: 'reload', summary: 'Fan out /reload-plugins to one or more teammates.', registry: 'none' },
+  { name: 'ls', summary: 'List running teammate tmux sessions.', registry: 'none' },
+  { name: 'states', summary: 'One-line fleet snapshot of every teammate.', registry: 'none' },
+  { name: 'ctx', summary: 'Report real ctx-window usage for one or more teammates.', registry: 'none' },
+  { name: 'history', summary: "Inspect a teammate repo's past sessions.", registry: 'none' },
+  { name: 'mem', summary: "Print a sibling repo's auto-memory index.", registry: 'none' },
+  { name: 'archive', summary: 'Move a finished task from the active ledger to the archive (reads stdin).', registry: 'none' },
+  { name: 'status', summary: "Capture-pane a teammate's live screen (diagnostic).", registry: 'none' },
+  { name: 'poll', summary: "Block until a teammate's pane matches a regex (diagnostic).", registry: 'none' },
+  { name: 'doctor', summary: 'Self-check: tm path/version, env, tmux, idle dir, active teammates.', registry: 'none' },
+  { name: 'ask', summary: 'Borrow an idle codex teammate from the pool, drive one turn on a fresh thread, return the teammate.', registry: 'none' },
+]

package/src/ws-types.d.ts

@@ -0,0 +1,9 @@
+// Type-only shim: `#ws` is the package.json `imports` alias for our vendored
+// copy of `ws` (under `third_party/ws/`). The runtime resolves it to the
+// vendored `wrapper.mjs`; this declaration re-exports the upstream `@types/ws`
+// type surface against the `#ws` specifier so the TypeScript checker can
+// follow imports without a `paths`-mapping trick.
+declare module '#ws' {
+  export * from 'ws'
+  export { default } from 'ws'
+}

package/third_party/ws/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Einar Otto Stangvik <einaros@gmail.com>
+Copyright (c) 2013 Arnout Kazemier and contributors
+Copyright (c) 2016 Luigi Pinca and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.