typeclaw 0.3.1 → 0.4.0

package/src/init/run-bun-install.ts

@@ -1,12 +1,21 @@
 export type InstallResult = { ok: true } | { ok: false; reason: string }
 
+export type InstallRunnerOptions = {
+  // Append `--force` to the bun install argv to bypass the cache for
+  // `file:` / `link:` deps. Bun treats name+version of a `file:` dep as a
+  // cache hit even after the source on disk has changed, so changes to a
+  // locally-linked typeclaw never propagate into <agent>/node_modules until
+  // either the typeclaw version is bumped or the install is forced.
+  force?: boolean
+}
+
 // Signature for the function `runInit` uses to materialize the agent folder's
 // dependencies. Exposed as a named type so callers (and tests) can pass their
 // own stub without re-declaring the shape, mirroring `HatchRunner` and
 // `KakaotalkAuthRunner` in `./index.ts`.
-export type InstallRunner = (cwd: string) => Promise<InstallResult>
+export type InstallRunner = (cwd: string, opts?: InstallRunnerOptions) => Promise<InstallResult>
 
-export async function runBunInstall(cwd: string): Promise<InstallResult> {
+export async function runBunInstall(cwd: string, opts?: InstallRunnerOptions): Promise<InstallResult> {
   const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
   if (!bun) return { ok: false, reason: 'bun runtime not available' }
   try {
@@ -21,7 +30,12 @@ export async function runBunInstall(cwd: string): Promise<InstallResult> {
       // the bug are non-trivial. Hoisted is the fallback strategy bun shipped
       // before 1.3 — slightly slower for huge monorepos, indistinguishable
       // for an agent folder, and not affected by the bug.
-      cmd: ['bun', 'install', '--linker=hoisted'],
+      //
+      // `--force` is conditional: it bypasses the package cache so file:/link:
+      // deps re-copy their current on-disk source into node_modules. Bun's
+      // file-dep cache is keyed on name+version, so without --force, edits to
+      // a `file:..` typeclaw never reach the container after the first install.
+      cmd: opts?.force ? ['bun', 'install', '--linker=hoisted', '--force'] : ['bun', 'install', '--linker=hoisted'],
       cwd,
       stdout: 'pipe',
       stderr: 'pipe',

package/src/init/run-owner-claim.ts

@@ -8,6 +8,7 @@ import type { ChannelKind } from './index'
 const CHANNEL_LABELS: Record<ChannelKind, string> = {
   'slack-bot': 'Slack',
   'discord-bot': 'Discord',
+  github: 'GitHub',
   'telegram-bot': 'Telegram',
   kakaotalk: 'KakaoTalk',
 }
@@ -25,9 +26,17 @@ export type RunOwnerClaimOptions = {
 // normal hatching path so the TUI still opens — the operator can run
 // `typeclaw role claim` later.
 export async function runOwnerClaim({ url, configuredChannels }: RunOwnerClaimOptions): Promise<void> {
-  if (configuredChannels.length === 0) return
+  // GitHub has no DM affordance, and the github adapter doesn't yet route
+  // claim codes (the `typeclaw role claim` CLI explicitly lists only the
+  // four chat adapters as --channel values). Owner authorization for github
+  // is handled by the `roles.member.match[]` repo allowlist that
+  // runAddChannel writes during init. Filtering here keeps the auto-claim
+  // working for chat channels mixed with github, and skips the flow
+  // entirely when github is the only wired channel.
+  const claimable = configuredChannels.filter((c) => c !== 'github')
+  if (claimable.length === 0) return
 
-  const channelList = configuredChannels.map((c) => CHANNEL_LABELS[c] ?? c).join(', ')
+  const channelList = claimable.map((c) => CHANNEL_LABELS[c] ?? c).join(', ')
 
   const proceed = await confirm({
     message: `Claim owner role on ${channelList} now?`,

package/src/permissions/builtins.ts

@@ -37,7 +37,12 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
   },
   trusted: {
     match: [],
-    permissions: [CORE_PERMISSIONS.channelRespond, CORE_PERMISSIONS.cronSchedule, 'security.bypass.secretExfilBash'],
+    permissions: [
+      CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.cronSchedule,
+      'security.bypass.secretExfilBash',
+      'security.bypass.gitExfil',
+    ],
   },
   member: {
     match: [],

package/src/permissions/match-rule.ts

@@ -16,7 +16,7 @@
 // error messages with typo suggestions; a single big regex would only ever
 // say "didn't match".
 
-export const PLATFORMS = ['slack', 'discord', 'telegram', 'kakao'] as const
+export const PLATFORMS = ['slack', 'discord', 'telegram', 'kakao', 'github'] as const
 export type Platform = (typeof PLATFORMS)[number]
 
 const SUBAGENT_NAME = /^[a-z][a-z0-9-]*$/
@@ -50,7 +50,7 @@ export type ParseMatchRuleResult = { ok: true; value: MatchRule } | { ok: false;
 // this to `author:` only, the JSON schema would reject typos with a generic
 // "did not match pattern" error and the user would lose the actionable hint.
 export const MATCH_RULE_REGEX_SOURCE =
-  '^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|kakao):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$'
+  '^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|kakao|github):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$'
 
 export function parseMatchRule(input: string): ParseMatchRuleResult {
   if (input !== input.trim() || input.length === 0) {
@@ -138,6 +138,8 @@ function parseChannelScope(platform: Platform, rest: string, author: string | un
     return { ok: true, value: buildChannelRule(platform, { author }) }
   }
 
+  if (platform === 'github') return parseGithubChannelScope(rest, author)
+
   // Bucket scopes: `dm/*`, `dm/<id>`, `group/*`, `open/*`. Slack's `im` is
   // renamed to `dm`; that mapping is enforced by the legacy-prefix table at
   // the top of parseMatchRule for unprefixed forms — here we just refuse the
@@ -203,6 +205,26 @@ function parseChannelScope(platform: Platform, rest: string, author: string | un
   return { ok: true, value: buildChannelRule(platform, { workspace: rest, author }) }
 }
 
+function parseGithubChannelScope(rest: string, author: string | undefined): ParseMatchRuleResult {
+  const [owner, repo, ...chatParts] = rest.split('/')
+  if (owner === undefined || owner === '' || repo === undefined || repo === '') {
+    return { ok: false, error: "github scope requires 'owner/repo' format" }
+  }
+  if (repo === '*') {
+    return {
+      ok: false,
+      error: `'github:${owner}/*' is not supported; use 'github:${owner}/repo' for a specific repo or 'github:*' for all github events`,
+    }
+  }
+  const workspace = `${owner}/${repo}`
+  if (chatParts.length === 0) return { ok: true, value: buildChannelRule('github', { workspace, author }) }
+  const chat = chatParts.join('/')
+  if (chat === '' || chat.includes('/')) {
+    return { ok: false, error: "github chat scope must be a single segment like 'issue:42'" }
+  }
+  return { ok: true, value: buildChannelRule('github', { workspace, chat, author }) }
+}
+
 function buildChannelRule(
   platform: Platform,
   parts: {

package/src/permissions/resolve.ts

@@ -5,6 +5,7 @@ import type { MatchRule, Platform } from './match-rule'
 const ADAPTER_TO_PLATFORM: Record<AdapterId, Platform> = {
   'slack-bot': 'slack',
   'discord-bot': 'discord',
+  github: 'github',
   'telegram-bot': 'telegram',
   kakaotalk: 'kakao',
 }

package/src/plugin/define.ts

@@ -1,16 +1,29 @@
 import type { z } from 'zod'
 
-import type { BuiltinToolRef, DefinedPlugin, PluginContext, PluginExports, Subagent, Tool } from './types'
+import type {
+  BuiltinToolRef,
+  ContainerCommand,
+  DefinedPlugin,
+  EitherCommand,
+  HostCommand,
+  PluginCommand,
+  PluginContext,
+  PluginExports,
+  Subagent,
+  Tool,
+} from './types'
 
 type DefinePluginSpec<S extends z.ZodType<unknown> | undefined> =
   S extends z.ZodType<infer T>
     ? {
         configSchema: S
         permissions?: readonly string[]
+        commands?: Record<string, PluginCommand>
         plugin: (ctx: PluginContext<T>) => Promise<PluginExports>
       }
     : {
         permissions?: readonly string[]
+        commands?: Record<string, PluginCommand>
         plugin: (ctx: PluginContext<unknown>) => Promise<PluginExports>
       }
 
@@ -28,6 +41,34 @@ export function defineSubagent<P>(subagent: Subagent<P>): Subagent<P> {
   return subagent
 }
 
+type ContainerCommandSpec<S extends z.ZodObject<z.ZodRawShape> | undefined> =
+  S extends z.ZodObject<z.ZodRawShape>
+    ? Omit<ContainerCommand<z.infer<S>>, 'args'> & { args: S }
+    : Omit<ContainerCommand<unknown>, 'args'> & { args?: undefined }
+
+type HostCommandSpec<S extends z.ZodObject<z.ZodRawShape> | undefined> =
+  S extends z.ZodObject<z.ZodRawShape>
+    ? Omit<HostCommand<z.infer<S>>, 'args'> & { args: S }
+    : Omit<HostCommand<unknown>, 'args'> & { args?: undefined }
+
+type EitherCommandSpec<S extends z.ZodObject<z.ZodRawShape> | undefined> =
+  S extends z.ZodObject<z.ZodRawShape>
+    ? Omit<EitherCommand<z.infer<S>>, 'args'> & { args: S }
+    : Omit<EitherCommand<unknown>, 'args'> & { args?: undefined }
+
+export function defineCommand<S extends z.ZodObject<z.ZodRawShape> | undefined = undefined>(
+  cmd: ContainerCommandSpec<S>,
+): ContainerCommand<S extends z.ZodObject<z.ZodRawShape> ? z.infer<S> : unknown>
+export function defineCommand<S extends z.ZodObject<z.ZodRawShape> | undefined = undefined>(
+  cmd: HostCommandSpec<S>,
+): HostCommand<S extends z.ZodObject<z.ZodRawShape> ? z.infer<S> : unknown>
+export function defineCommand<S extends z.ZodObject<z.ZodRawShape> | undefined = undefined>(
+  cmd: EitherCommandSpec<S>,
+): EitherCommand<S extends z.ZodObject<z.ZodRawShape> ? z.infer<S> : unknown>
+export function defineCommand(cmd: PluginCommand): PluginCommand {
+  return cmd
+}
+
 export const readTool: BuiltinToolRef = { __builtinTool: 'read' }
 export const bashTool: BuiltinToolRef = { __builtinTool: 'bash' }
 export const editTool: BuiltinToolRef = { __builtinTool: 'edit' }

package/src/plugin/index.ts

@@ -1,8 +1,9 @@
 export {
   bashTool,
-  defineTool,
+  defineCommand,
   definePlugin,
   defineSubagent,
+  defineTool,
   editTool,
   findTool,
   grepTool,
@@ -13,14 +14,24 @@ export {
 
 export type {
   BuiltinToolRef,
+  CommandExecResult,
+  CommandStreams,
+  ContainerCommand,
+  ContainerCommandContext,
   ContentPart,
   DefinedPlugin,
+  EitherCommand,
+  EitherCommandContext,
   HookContext,
   HookName,
   Hooks,
+  HostCommand,
+  HostCommandContext,
   PluginCheckResult,
   PluginCheckStatus,
+  PluginCommand,
   PluginContext,
+  CronHandlerContext,
   PluginCronJob,
   PluginDoctorCheck,
   PluginDoctorContext,
@@ -28,6 +39,7 @@ export type {
   PluginExports,
   PluginFixResult,
   PluginFixSuggestion,
+  PluginHandlerCronJob,
   PluginLogger,
   PluginPromptCronJob,
   PluginSkill,
@@ -61,12 +73,15 @@ export { loadPluginEntry, derivePluginNameFromPackage } from './loader'
 export { materializeSkills, type MaterializedSkills, type SkillEntry } from './skills'
 export {
   buildPluginCronGlobalId,
+  RESERVED_COMMAND_NAMES,
+  validateCommandDeclaration,
   type PluginRegistry,
+  type RegisteredCommand,
   type RegisteredCronJob,
   type RegisteredDoctorCheck,
+  type RegisteredSkillDir,
+  type RegisteredSkillEntry,
   type RegisteredSubagent,
   type RegisteredTool,
-  type RegisteredSkillEntry,
-  type RegisteredSkillDir,
 } from './registry'
 export { createHookBus, type HookBus } from './hooks'

package/src/plugin/manager.ts

@@ -117,6 +117,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
         pluginName: resolved.name,
         logger,
         exports,
+        ...(resolved.defined.commands !== undefined ? { commands: resolved.defined.commands } : {}),
         registry,
         hooks,
         agentDir: opts.agentDir,
@@ -166,6 +167,7 @@ export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], regi
     `${registry.skills.length} skill(s)`,
     `${registry.skillsDirs.length} skills dir(s)`,
     `${registry.doctorChecks.length} doctor check(s)`,
+    `${registry.commands.length} command(s)`,
   ].join(', ')
   return `${loaded.length} plugin(s): ${head} [${counts}]`
 }

package/src/plugin/registry.ts

@@ -1,9 +1,11 @@
 import { existsSync } from 'node:fs'
 
+import { BUILTIN_COMMAND_NAMES } from '@/cli/builtins'
 import type { CronJob, PromptJob } from '@/cron'
 
 import type { HookBus } from './hooks'
 import type {
+  PluginCommand,
   PluginCronJob,
   PluginDoctorCheck,
   PluginExports,
@@ -12,6 +14,7 @@ import type {
   Subagent,
   Tool,
 } from './types'
+import { isPrimitiveZodObject } from './zod-introspect'
 
 export type RegisteredTool = { pluginName: string; toolName: string; tool: Tool<any>; logger: PluginLogger }
 export type RegisteredSubagent = { pluginName: string; subagentName: string; subagent: Subagent<any> }
@@ -25,6 +28,12 @@ export type RegisteredDoctorCheck = {
   logger: PluginLogger
   check: PluginDoctorCheck
 }
+export type RegisteredCommand = {
+  pluginName: string
+  commandName: string
+  command: PluginCommand
+  logger: PluginLogger
+}
 
 export type PluginRegistry = {
   tools: RegisteredTool[]
@@ -33,18 +42,28 @@ export type PluginRegistry = {
   skills: RegisteredSkillEntry[]
   skillsDirs: RegisteredSkillDir[]
   doctorChecks: RegisteredDoctorCheck[]
+  commands: RegisteredCommand[]
 }
 
 export type RegisterContributionsOptions = {
   pluginName: string
   logger: PluginLogger
   exports: PluginExports
+  // Static commands declared on `DefinedPlugin.commands`. Passed alongside
+  // `exports` because they live outside the factory's return value.
+  commands?: Record<string, PluginCommand>
   registry: PluginRegistry
   hooks: HookBus
   agentDir: string
   pluginConfig: unknown
 }
 
+const COMMAND_NAME_REGEX = /^[a-z][a-z0-9-]*$/
+
+// CLI subcommands plugins MUST NOT shadow. Derived from BUILTIN_COMMAND_NAMES
+// so cli/index.ts and registry.ts cannot drift apart.
+export const RESERVED_COMMAND_NAMES: ReadonlySet<string> = new Set(BUILTIN_COMMAND_NAMES)
+
 export function buildPluginCronGlobalId(pluginName: string, localId: string): string {
   return `__plugin_${pluginName}_${localId}`
 }
@@ -127,6 +146,19 @@ export function registerContributions(opts: RegisterContributionsOptions): void
       registry.doctorChecks.push({ pluginName, checkName, pluginConfig, logger, check })
     }
   }
+
+  if (opts.commands) {
+    for (const [commandName, command] of Object.entries(opts.commands)) {
+      validateCommandDeclaration(pluginName, commandName, command)
+      const conflict = registry.commands.find((c) => c.commandName === commandName)
+      if (conflict) {
+        throw new Error(
+          `plugin ${pluginName}: command "${commandName}" already registered by plugin ${conflict.pluginName}`,
+        )
+      }
+      registry.commands.push({ pluginName, commandName, command, logger })
+    }
+  }
 }
 
 export function discardRegistrationsBy(pluginName: string, registry: PluginRegistry, hooks: HookBus): void {
@@ -136,11 +168,20 @@ export function discardRegistrationsBy(pluginName: string, registry: PluginRegis
   registry.skills = registry.skills.filter((s) => s.pluginName !== pluginName)
   registry.skillsDirs = registry.skillsDirs.filter((d) => d.pluginName !== pluginName)
   registry.doctorChecks = registry.doctorChecks.filter((d) => d.pluginName !== pluginName)
+  registry.commands = registry.commands.filter((c) => c.pluginName !== pluginName)
   hooks.unregisterAll(pluginName)
 }
 
 export function emptyRegistry(): PluginRegistry {
-  return { tools: [], subagents: [], cronJobs: [], skills: [], skillsDirs: [], doctorChecks: [] }
+  return {
+    tools: [],
+    subagents: [],
+    cronJobs: [],
+    skills: [],
+    skillsDirs: [],
+    doctorChecks: [],
+    commands: [],
+  }
 }
 
 function assertNotEmpty(kind: string, value: string, pluginName: string): void {
@@ -149,6 +190,36 @@ function assertNotEmpty(kind: string, value: string, pluginName: string): void {
   }
 }
 
+function assertValidCommandArgsSchema(pluginName: string, commandName: string, command: PluginCommand): void {
+  if (command.args === undefined) return
+  if (!isPrimitiveZodObject(command.args)) {
+    throw new Error(
+      `plugin ${pluginName}: command "${commandName}" args must be a z.object({...}) with primitive (string/number/boolean) leaves`,
+    )
+  }
+}
+
+// Reuses the same checks `registerContributions` runs at boot, so host-stage
+// discovery and runtime registration agree on what is a valid command. Throws
+// a precise error referencing the plugin and command; callers translate the
+// error into a discovery `loadError` rather than failing the whole CLI.
+export function validateCommandDeclaration(pluginName: string, commandName: string, command: PluginCommand): void {
+  if (commandName.length === 0) {
+    throw new Error(`plugin ${pluginName}: empty command name`)
+  }
+  if (!COMMAND_NAME_REGEX.test(commandName)) {
+    throw new Error(
+      `plugin ${pluginName}: command "${commandName}" does not match ${COMMAND_NAME_REGEX.source} (lowercase letters, digits, dashes; must start with a letter)`,
+    )
+  }
+  if (RESERVED_COMMAND_NAMES.has(commandName)) {
+    throw new Error(
+      `plugin ${pluginName}: command "${commandName}" shadows a built-in typeclaw subcommand and cannot be registered`,
+    )
+  }
+  assertValidCommandArgsSchema(pluginName, commandName, command)
+}
+
 function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
   // Plugin-contributed jobs default to `owner` because they are part of the
   // agent's bundled (or operator-installed) runtime, not user-channel
@@ -171,12 +242,23 @@ function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
     }
     return job
   }
+  if (spec.kind === 'exec') {
+    return {
+      id: globalId,
+      schedule: spec.schedule,
+      enabled: spec.enabled ?? true,
+      kind: 'exec',
+      command: spec.command,
+      scheduledByRole,
+      ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
+    }
+  }
   return {
     id: globalId,
     schedule: spec.schedule,
     enabled: spec.enabled ?? true,
-    kind: 'exec',
-    command: spec.command,
+    kind: 'handler',
+    handler: spec.handler,
     scheduledByRole,
     ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
   }

package/src/plugin/types.ts

@@ -92,7 +92,58 @@ export type PluginExecCronJob = {
   timezone?: string
 }
 
-export type PluginCronJob = PluginPromptCronJob | PluginExecCronJob
+// In-process handler. Invoked directly by the cron consumer; no shell-out, no
+// WS round-trip, no Bun.spawn. Use this when the cron job needs imperative
+// control flow (probe → maybe prompt → write file) and lives in the same
+// plugin as the logic — there is no need to dress the work up as a CLI
+// command just to schedule it from yourself.
+//
+// `handler` is a TypeScript function reference, so this kind CANNOT appear in
+// cron.json (only plugin-contributed cron registrations can carry it). The
+// schema gate (`parseCronFile` in src/cron/schema.ts) keeps user files limited
+// to `prompt` and `exec`.
+export type PluginHandlerCronJob = {
+  schedule: string
+  kind: 'handler'
+  handler: (ctx: CronHandlerContext) => Promise<void>
+  enabled?: boolean
+  timezone?: string
+}
+
+export type PluginCronJob = PluginPromptCronJob | PluginExecCronJob | PluginHandlerCronJob
+
+// Surface passed into a plugin cron handler. Mirrors the LLM-call capabilities
+// of `ContainerCommandContext` (`prompt`, `subagent`, `exec`) without the
+// CLI-shaped fields (stdin/stdout/stderr, args, exit code) because cron has
+// no caller to pipe to.
+//
+// `signal` is reserved for future cancellation and is currently never aborted
+// by the runtime — the consumer matches the existing prompt/exec cron jobs
+// which also let in-flight work finish on container shutdown. The signal IS
+// already threaded into `ctx.prompt` and `ctx.exec`, so the moment the
+// runtime starts aborting it (e.g. via a future graceful-shutdown path),
+// propagation works without handler-author changes. Handler authors who
+// want to respect future cancellation should still check `ctx.signal.aborted`
+// in long-running loops; nothing fires it today.
+//
+// `origin` is a cron-shaped SessionOrigin so any session the handler spawns
+// via `ctx.prompt` carries the cron job's provenance — same role-inheritance
+// semantics as a `kind: 'exec'` job that shells out to `typeclaw <cmd>`.
+export type CronHandlerContext = {
+  readonly jobId: string
+  // The plugin that registered this cron job (e.g. 'inbox-watch'). Matches
+  // `ContainerCommandContext.name`. Useful for log lines that should be
+  // attributable to the plugin, not just the cron id.
+  readonly name: string
+  readonly agentDir: string
+  readonly logger: PluginLogger
+  readonly signal: AbortSignal
+  readonly permissions: PermissionService
+  readonly origin: SessionOrigin
+  readonly prompt: (text: string) => Promise<string>
+  readonly subagent: (name: string, payload?: unknown) => Promise<void>
+  readonly exec: (cmd: TemplateStringsArray, ...values: unknown[]) => Promise<CommandExecResult>
+}
 
 export type PluginSkill = {
   description: string
@@ -267,5 +318,91 @@ export type PluginFixResult = {
 export type DefinedPlugin<TConfig = never> = {
   readonly configSchema?: z.ZodType<TConfig>
   readonly permissions?: readonly string[]
+  // Declared by-value (not built inside the factory) so the host-stage CLI
+  // can dispatch commands without booting plugin runtime state.
+  readonly commands?: Record<string, PluginCommand>
   readonly plugin: (ctx: PluginContext<TConfig>) => Promise<PluginExports>
 }
+
+// `surface` controls where a plugin command may run: `'container'` requires
+// the agent runtime (prompt/subagent/exec); `'host'` runs on the user's
+// machine with no agent runtime; `'either'` accepts the intersection ctx
+// and runs on whichever stage the user invoked it from.
+export type PluginCommand = ContainerCommand | HostCommand | EitherCommand
+
+export type ContainerCommand<A = unknown> = {
+  readonly surface: 'container'
+  readonly description: string
+  // v1 constraint: `z.object({...})` with primitive (string/number/boolean/
+  // literal/enum) leaves so `--help` can render `--<name>=<type>`.
+  readonly args?: z.ZodObject<z.ZodRawShape>
+  readonly permissions?: readonly string[]
+  // When true, runtime spawns a fresh Bun subprocess instead of dispatching
+  // in-process. Costs ~150ms cold-start; trade for isolation from the agent.
+  readonly isolated?: boolean
+  readonly run: (ctx: ContainerCommandContext, args: A) => Promise<number>
+}
+
+export type HostCommand<A = unknown> = {
+  readonly surface: 'host'
+  readonly description: string
+  readonly args?: z.ZodObject<z.ZodRawShape>
+  readonly run: (ctx: HostCommandContext, args: A) => Promise<number>
+}
+
+export type EitherCommand<A = unknown> = {
+  readonly surface: 'either'
+  readonly description: string
+  readonly args?: z.ZodObject<z.ZodRawShape>
+  readonly run: (ctx: EitherCommandContext, args: A) => Promise<number>
+}
+
+export type CommandStreams = {
+  readonly stdin: ReadableStream<Uint8Array>
+  readonly stdout: WritableStream<Uint8Array>
+  readonly stderr: WritableStream<Uint8Array>
+}
+
+export type CommandExecResult = {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number
+}
+
+export type ContainerCommandContext = CommandStreams & {
+  // The plugin name (e.g. `'my-utilities'`), NOT the command name. Matches
+  // `PluginContext.name`. Use the command's own static name if you need it.
+  readonly name: string
+  readonly version: string | undefined
+  readonly agentDir: string
+  readonly logger: PluginLogger
+  readonly permissions: PermissionService
+  // Caller's origin (cron job, TUI op, parent session). Drives permission
+  // resolution inside the command. Dispatcher refuses to run without one.
+  readonly origin: SessionOrigin
+  readonly signal: AbortSignal
+  readonly prompt: (text: string) => Promise<string>
+  readonly subagent: (name: string, payload?: unknown) => Promise<void>
+  readonly exec: (cmd: TemplateStringsArray, ...values: unknown[]) => Promise<CommandExecResult>
+}
+
+export type HostCommandContext = CommandStreams & {
+  // The plugin name, NOT the command name. See `ContainerCommandContext.name`.
+  readonly name: string
+  readonly version: string | undefined
+  // Host path of the agent folder (e.g. the absolute path to the agent
+  // folder), NOT `/agent`.
+  readonly agentDir: string
+  readonly logger: PluginLogger
+  readonly signal: AbortSignal
+}
+
+export type EitherCommandContext = CommandStreams & {
+  // The plugin name, NOT the command name. See `ContainerCommandContext.name`.
+  readonly name: string
+  readonly version: string | undefined
+  // Resolves to `/agent` in container, host path on host — same author code.
+  readonly agentDir: string
+  readonly logger: PluginLogger
+  readonly signal: AbortSignal
+}