Initial commit: AirCoding V1.0.0 Alpha architecture baseline

Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
2026-05-28 18:45:01 +08:00
commit 82f3140847
366 changed files with 123826 additions and 0 deletions
--- a/AirPlan/docs/architecture/tool-registry-v1.md
+++ b/AirPlan/docs/architecture/tool-registry-v1.md
@@ -0,0 +1,761 @@
+# AirCoding V1.0.0 Alpha Tool Registry V1
+
+Date: 2026-05-27
+Status: Canonical V1.0.0 Alpha built-in tool registry
+
+This document freezes the built-in tools required for the V1.0.0 Alpha skeleton. Additional tools may be added by capabilities/plugins later, but the tools here define the minimum stable execution surface.
+
+Tool contract is defined in `interface-contracts-v1.md` §12 and exported from `packages/contracts/tool.ts`.
+
+## 1. Registry Principles
+
+1. Tools are schema-validated at input and output boundaries.
+2. Tools emit lifecycle events from `event-registry-v1.md`: `tool.started`, `tool.progress`, `tool.completed`, `tool.failed`, `tool.cancelled`.
+3. Tools must go through PermissionEngine before filesystem writes, command execution, network access, or system-sensitive operations.
+4. File edit tools follow Claude Code style discipline: read-before-edit, exact replacement, small edits, no broad rewrite unless the tool is explicitly `fs.write` or template scaffolding.
+5. Shell tools capture stdout/stderr as artifacts when output exceeds inline limits or when the command participates in verification evidence.
+6. Tool implementations return structured outputs; human-readable summaries are presentation data, not the source of truth.
+7. Tool names are stable API identifiers and use dotted namespaces.
+
+## 2. Common Tool Types
+
+`ToolCategory`, `ToolResultEnvelope`, `ToolDefinition`, `ToolExecutor`, `StreamingToolExecutor`, and `ToolRegistry` are defined in `interface-contracts-v1.md` §12. This document references those contracts; it does not re-define them.
+
+Inline output limits are implementation config, but V1 defaults should be conservative:
+
+```text
+stdout/stderr inline preview: 16 KiB each
+file read inline default: 2000 lines
+single tool event payload target: < 256 KiB
+larger content: artifact reference
+```
+
+## 3. Filesystem Tools
+
+### `fs.list` v1
+
+Category: filesystem. Permission: read paths.
+
+Purpose: list directory entries with metadata.
+
+Input:
+
+```ts
+interface FsListInput {
+  path: string
+  recursive?: boolean
+  max_depth?: number
+  include_hidden?: boolean
+  glob?: string
+}
+```
+
+Output:
+
+```ts
+interface FsListOutput {
+  entries: Array<{
+    path: string
+    type: "file" | "directory" | "symlink" | "other"
+    size_bytes?: number
+    modified_at?: string
+    target_path?: string
+  }>
+  truncated: boolean
+}
+```
+
+### `fs.read` v1
+
+Category: filesystem. Permission: read paths.
+
+Purpose: read text, binary metadata, images, PDFs, or notebooks through typed adapters.
+
+Input:
+
+```ts
+interface FsReadInput {
+  path: string
+  offset_lines?: number
+  limit_lines?: number
+  pages?: string
+  encoding?: "utf8" | "base64" | "auto"
+}
+```
+
+Output:
+
+```ts
+interface FsReadOutput {
+  path: string
+  content?: string
+  content_type: "text" | "binary" | "image" | "pdf" | "notebook" | "empty"
+  line_count?: number
+  truncated: boolean
+  artifact_id?: string
+}
+```
+
+### `fs.write` v1
+
+Category: filesystem. Permission: write paths.
+
+Purpose: create new files or overwrite files only when explicitly authorized by the caller policy.
+
+Input:
+
+```ts
+interface FsWriteInput {
+  path: string
+  content: string
+  create_parent_dirs?: boolean
+  expected_existing_sha256?: string
+}
+```
+
+Output:
+
+```ts
+interface FsWriteOutput {
+  path: string
+  bytes_written: number
+  sha256: string
+  backup_artifact_id?: string
+}
+```
+
+### `fs.edit` v1
+
+Category: filesystem. Permission: read/write paths.
+
+Purpose: exact string replacement in an existing file.
+
+Input:
+
+```ts
+interface FsEditInput {
+  path: string
+  old_string: string
+  new_string: string
+  replace_all?: boolean
+  expected_existing_sha256?: string
+}
+```
+
+Output:
+
+```ts
+interface FsEditOutput {
+  path: string
+  replacements: number
+  sha256: string
+  diff_artifact_id: string
+}
+```
+
+Rules:
+
+- The file must have been read in the active task before edit.
+- `old_string` must be unique unless `replace_all = true`.
+- The tool fails rather than guessing indentation or nearby replacements.
+
+### `fs.patch` v1
+
+Category: filesystem. Permission: read/write paths.
+
+Purpose: apply a unified patch generated by the execution layer.
+
+Input:
+
+```ts
+interface FsPatchInput {
+  patch: string
+  strip?: number
+  expected_paths?: string[]
+}
+```
+
+Output:
+
+```ts
+interface FsPatchOutput {
+  changed_files: string[]
+  diff_artifact_id: string
+  rejected_hunks_artifact_id?: string
+}
+```
+
+### `fs.stat` v1
+
+Category: filesystem. Permission: read paths.
+
+Purpose: inspect path metadata and realpath for permission decisions.
+
+Input:
+
+```ts
+interface FsStatInput { path: string }
+```
+
+Output:
+
+```ts
+interface FsStatOutput {
+  path: string
+  realpath?: string
+  exists: boolean
+  type?: "file" | "directory" | "symlink" | "other"
+  size_bytes?: number
+  modified_at?: string
+}
+```
+
+## 4. Shell and Process Tools
+
+### `shell.run` v1
+
+Category: shell. Permission: execute plus command risk analysis.
+
+Purpose: run a bounded non-interactive command.
+
+Input:
+
+```ts
+interface ShellRunInput {
+  command: string
+  cwd: string
+  timeout_ms?: number
+  env?: Record<string, string>
+  stdin?: string
+  capture_mode?: "inline" | "artifact" | "both"
+  purpose?: "build" | "test" | "debug" | "doctor" | "general"
+}
+```
+
+Output:
+
+```ts
+interface ShellRunOutput {
+  command_run_id: string
+  exit_code: number
+  duration_ms: number
+  stdout_preview?: string
+  stderr_preview?: string
+  stdout_artifact_id?: string
+  stderr_artifact_id?: string
+  combined_artifact_id?: string
+  parsed_diagnostics_json?: unknown
+}
+```
+
+Rules:
+
+- No interactive commands in V1 unless a dedicated tool owns the interaction model.
+- Destructive commands require PermissionEngine approval based on command risk analysis.
+- The command runner emits `command.started`, command stream deltas, and terminal command events.
+
+### `process.kill` v1
+
+Category: shell/debug. Permission: execute; system-sensitive when target is outside AirCoding process tree.
+
+Input:
+
+```ts
+interface ProcessKillInput {
+  pid: number
+  signal?: "SIGTERM" | "SIGKILL" | "SIGINT"
+  reason: string
+}
+```
+
+Output:
+
+```ts
+interface ProcessKillOutput {
+  pid: number
+  signal: string
+  delivered: boolean
+}
+```
+
+## 5. Git Tools
+
+### `git.status` v1
+
+Category: git. Permission: read paths.
+
+Input:
+
+```ts
+interface GitStatusInput { cwd: string }
+```
+
+Output:
+
+```ts
+interface GitStatusOutput {
+  branch?: string
+  clean: boolean
+  staged: string[]
+  modified: string[]
+  untracked: string[]
+  conflicted: string[]
+}
+```
+
+### `git.diff` v1
+
+Category: git. Permission: read paths.
+
+Input:
+
+```ts
+interface GitDiffInput {
+  cwd: string
+  base_ref?: string
+  pathspecs?: string[]
+  staged?: boolean
+}
+```
+
+Output:
+
+```ts
+interface GitDiffOutput {
+  diff: string
+  diff_artifact_id?: string
+  truncated: boolean
+}
+```
+
+### `git.worktree.create` v1
+
+Category: git. Permission: write project-local paths.
+
+Input:
+
+```ts
+interface GitWorktreeCreateInput {
+  cwd: string
+  path: string
+  branch_name: string
+  base_ref?: string
+}
+```
+
+Output:
+
+```ts
+interface GitWorktreeCreateOutput {
+  workspace_id: string
+  path: string
+  branch_name: string
+  base_ref?: string
+}
+```
+
+### `git.merge_workspace` v1
+
+Category: git. Permission: write project paths.
+
+Input:
+
+```ts
+interface GitMergeWorkspaceInput {
+  workspace_id: string
+  strategy: "fast_forward" | "patch_apply" | "manual_merge"
+  target_ref?: string
+}
+```
+
+Output:
+
+```ts
+interface GitMergeWorkspaceOutput {
+  status: "merged" | "conflicted" | "failed"
+  changed_files: string[]
+  diff_artifact_id?: string
+  conflict_artifact_id?: string
+}
+```
+
+## 6. Project Tools
+
+### `project.scan` v1
+
+Category: project. Permission: read project paths.
+
+Purpose: collect project metadata for initialization and profile updates.
+
+Input:
+
+```ts
+interface ProjectScanInput {
+  project_root: string
+  include_directory_tree: true
+  include_git_summary?: boolean
+  include_extension_stats?: boolean
+  include_special_files?: boolean
+}
+```
+
+Output:
+
+```ts
+interface ProjectScanOutput {
+  project_root: string
+  directory_tree_artifact_id: string
+  extension_stats: Record<string, number>
+  special_files: string[]
+  git_summary?: unknown
+}
+```
+
+### `project.profile.write` v1
+
+Category: project. Permission: write `.air/shared/project.json`.
+
+Input:
+
+```ts
+interface ProjectProfileWriteInput {
+  project_root: string
+  profile_json: unknown
+  expected_schema_version?: number
+}
+```
+
+Output:
+
+```ts
+interface ProjectProfileWriteOutput {
+  path: string
+  schema_version: number
+  sha256: string
+}
+```
+
+## 7. C++ Toolchain MVP Tools
+
+### `cpp.detect` v1
+
+Category: build. Permission: read project paths.
+
+Output includes detected build systems, compiler hints, test frameworks, and confidence notes.
+
+```ts
+interface CppDetectInput { project_root: string }
+interface CppDetectOutput {
+  build_systems: Array<"cmake" | "make" | "ninja" | "custom" | "unknown">
+  preferred_build_system?: string
+  source_roots: string[]
+  test_roots: string[]
+  notes: string[]
+}
+```
+
+### `cpp.cmake.configure` v1
+
+Category: build. Permission: execute and write build directory.
+
+```ts
+interface CppCmakeConfigureInput {
+  project_root: string
+  build_dir: string
+  generator_preference?: "ninja_then_make" | "ninja" | "make"
+  cmake_args?: string[]
+}
+interface CppCmakeConfigureOutput {
+  command_run_id: string
+  compile_commands_path?: string
+  diagnostics?: unknown
+}
+```
+
+### `cpp.build` v1
+
+Category: build. Permission: execute and write build directory.
+
+```ts
+interface CppBuildInput {
+  project_root: string
+  build_dir?: string
+  target?: string
+  clean_first?: boolean
+}
+interface CppBuildOutput {
+  command_run_id: string
+  status: "passed" | "failed"
+  diagnostics?: unknown
+}
+```
+
+### `cpp.test` v1
+
+Category: test. Permission: execute project/build outputs.
+
+```ts
+interface CppTestInput {
+  project_root: string
+  build_dir?: string
+  framework?: "ctest" | "gtest" | "custom"
+  filter?: string
+}
+interface CppTestOutput {
+  command_run_id: string
+  status: "passed" | "failed"
+  test_count?: number
+  failed_tests?: string[]
+  report_artifact_id?: string
+}
+```
+
+### `cpp.static.cppcheck` v1
+
+Category: static_analysis. Permission: execute/read project paths.
+
+```ts
+interface CppcheckInput {
+  project_root: string
+  paths?: string[]
+  compile_commands_path?: string
+}
+interface CppcheckOutput {
+  command_run_id: string
+  diagnostic_ids: string[]
+  report_artifact_id?: string
+}
+```
+
+### `cpp.clangd.query` v1
+
+Category: static_analysis. Permission: read project paths and execute clangd helper.
+
+```ts
+interface ClangdQueryInput {
+  project_root: string
+  compile_commands_path?: string
+  query: "definition" | "references" | "symbols" | "diagnostics"
+  file?: string
+  line?: number
+  column?: number
+  symbol?: string
+}
+interface ClangdQueryOutput {
+  results: unknown
+  artifact_id?: string
+}
+```
+
+## 8. Debug and Evidence Tools
+
+### `debug.run` v1
+
+Category: debug. Permission: execute project/build outputs.
+
+```ts
+interface DebugRunInput {
+  command: string
+  cwd: string
+  timeout_ms?: number
+  collect_core_dump?: boolean
+  collect_backtrace?: boolean
+}
+interface DebugRunOutput {
+  command_run_id: string
+  exit_code?: number
+  crash_detected: boolean
+  backtrace_artifact_id?: string
+  core_dump_artifact_id?: string
+}
+```
+
+### `debug.parse_logs` v1
+
+Category: debug. Permission: read paths.
+
+```ts
+interface DebugParseLogsInput {
+  paths: string[]
+  task_id?: string
+  hint?: string
+}
+interface DebugParseLogsOutput {
+  diagnostic_ids: string[]
+  summary: string
+  report_artifact_id?: string
+}
+```
+
+## 9. GUI and Network Evidence Tools
+
+### `gui.screenshot` v1
+
+Category: gui. Permission: read display/session state; system-sensitive if outside controlled test display.
+
+```ts
+interface GuiScreenshotInput {
+  target: "active_window" | "display" | "window_title" | "pid"
+  value?: string
+}
+interface GuiScreenshotOutput {
+  screenshot_artifact_id: string
+  width?: number
+  height?: number
+}
+```
+
+### `network.capture` v1
+
+Category: network. Permission: network and system-sensitive when packet capture requires elevated permissions.
+
+```ts
+interface NetworkCaptureInput {
+  interface?: string
+  duration_ms: number
+  filter?: string
+  reason: string
+}
+interface NetworkCaptureOutput {
+  pcap_artifact_id?: string
+  summary_artifact_id?: string
+  packet_count?: number
+}
+```
+
+## 10. Context, Artifact, Permission, and Doctor Tools
+
+### `artifact.create` v1
+
+Category: artifact. Permission: write session artifact path.
+
+```ts
+interface ArtifactCreateInput {
+  type: string
+  original_name?: string
+  content?: string
+  source_path?: string
+  associated_entity_type?: string
+  associated_entity_id?: string
+  metadata?: Record<string, unknown>
+}
+interface ArtifactCreateOutput {
+  artifact_id: string
+  uri: string
+  path: string
+  sha256?: string
+  size_bytes?: number
+}
+```
+
+### `context.assemble` v1
+
+Category: context. Permission: read DB/artifacts/rules.
+
+```ts
+interface ContextAssembleInput {
+  task_id?: string
+  purpose: "main" | "execute" | "review" | "debug" | "compact" | "mine_experience"
+  refs?: string[]
+  token_budget?: number
+}
+interface ContextAssembleOutput {
+  canonical_format: "anthropic"
+  messages_artifact_id: string
+  omissions: string[]
+  token_estimate?: number
+  compaction_requested?: boolean
+}
+```
+
+### `permission.request` v1
+
+Category: permission. Permission: internal.
+
+```ts
+interface PermissionRequestInput {
+  subject: string
+  risk_level: "low" | "medium" | "high" | "critical"
+  reason: string
+  options: string[]
+  default_option?: string
+  request_ref?: unknown
+}
+interface PermissionRequestOutput {
+  prompt_id: string
+  selected_option?: string
+  decision_id?: string
+}
+```
+
+### `doctor.run` v1
+
+Category: doctor. Permission: read system/project state; fix mode may require execute/write.
+
+```ts
+interface DoctorRunInput {
+  mode: "read_only" | "fix"
+  scope?: "startup" | "project" | "toolchain" | "release_gate"
+  capabilities?: string[]
+}
+interface DoctorRunOutput {
+  run_id: string
+  status: "passed" | "issues_found" | "fixed" | "failed"
+  issue_count: number
+  blocking_issue_count: number
+  report_artifact_id?: string
+}
+```
+
+## 11. MVP Required Tool Index
+
+```text
+fs.list
+fs.read
+fs.write
+fs.edit
+fs.patch
+fs.stat
+shell.run
+process.kill
+git.status
+git.diff
+git.worktree.create
+git.merge_workspace
+project.scan
+project.profile.write
+cpp.detect
+cpp.cmake.configure
+cpp.build
+cpp.test
+cpp.static.cppcheck
+cpp.clangd.query
+debug.run
+debug.parse_logs
+gui.screenshot
+network.capture
+artifact.create
+context.assemble
+permission.request
+doctor.run
+```
+
+## 12. Post-MVP Tool Candidates
+
+These are intentionally not required for the V1.0.0 Alpha skeleton:
+
+```text
+image.generate
+image.edit
+browser.automate
+gui.interact
+container.run
+package.manager.install
+mcp.call
+skill.run
+clang-tidy native wrapper
+sanitizer runner
+coverage reporter
+```
+
+They may be registered by capabilities once the V1 registry, permission model, event schema, and artifact model are stable.