diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 97bcf52612..508c828e09 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,5 +1,5 @@ name: Bug report -description: Report a defect in Maka (Desktop, TUI/CLI, or Headless) +description: Report a defect in Maka (Desktop, TUI/CLI, Runtime Host, or Eval) labels: ["bug"] body: - type: textarea @@ -29,7 +29,7 @@ body: placeholder: | - Maka version or commit: - OS and version: - - Surface: Desktop / TUI / CLI / Headless + - Surface: Desktop / TUI / CLI / Runtime Host / Eval - Node.js version, if running from source: validations: required: true diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d550459e0e..d0d95a7c37 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,7 +16,6 @@ jobs: outputs: code: ${{ steps.plan.outputs.code }} e2e: ${{ steps.plan.outputs.e2e }} - headless: ${{ steps.plan.outputs.headless }} runtime_host: ${{ steps.plan.outputs.runtime_host }} runtime_sandbox: ${{ steps.plan.outputs.runtime_sandbox }} script_mode: ${{ steps.plan.outputs.script_mode }} @@ -152,46 +151,16 @@ jobs: - name: Run Runtime Host tests run: npm --workspace @maka/runtime-host run test:dist - test_headless: - needs: changes - if: needs.changes.outputs.headless == 'true' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 - with: - node-version: '24' - cache: npm - - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0 - - name: Install pinned Harbor contract runtime - run: | - uv tool install "harbor==0.13.2" - uv tool dir --bin >> "$GITHUB_PATH" - - name: Install Linux runtime dependencies - run: sudo apt-get update && sudo apt-get install -y ripgrep bubblewrap - - run: npm ci - - run: npm run build:test - - name: Run Headless tests - env: - MAKA_REQUIRE_HARBOR_CONTRACT: '1' - run: npm --workspace @maka/headless run test:dist - # The Harbor adapters are Python, so their contracts cannot ride the - # workspace suite. This one needs only the stdlib. - - name: Run Harbor adapter tests - run: python3 packages/headless/harbor/tests/test_process_scope.py - # Preserve one stable required check while letting independent heavy suites # occupy their own runners. The aggregator waits for every selected lane. test: - needs: [changes, test_workspaces, test_runtime_host, test_headless] + needs: [changes, test_workspaces, test_runtime_host] if: always() runs-on: ubuntu-latest steps: - name: Require successful test lanes env: CHANGES_RESULT: ${{ needs.changes.result }} - HEADLESS_RESULT: ${{ needs.test_headless.result }} - HEADLESS_SELECTED: ${{ needs.changes.outputs.headless }} RUNTIME_HOST_RESULT: ${{ needs.test_runtime_host.result }} RUNTIME_HOST_SELECTED: ${{ needs.changes.outputs.runtime_host }} SCRIPT_MODE: ${{ needs.changes.outputs.script_mode }} @@ -221,7 +190,6 @@ jobs: fi require_lane "workspace tests" "$workspaces_selected" "$WORKSPACES_RESULT" require_lane "Runtime Host tests" "$RUNTIME_HOST_SELECTED" "$RUNTIME_HOST_RESULT" - require_lane "Headless tests" "$HEADLESS_SELECTED" "$HEADLESS_RESULT" # One Electron job: install once, run the (now small) e2e suite, then the # CDP alignment audit against the same built renderer. Dual shards plus a diff --git a/.github/workflows/oracle-evidence-audit.yml b/.github/workflows/oracle-evidence-audit.yml deleted file mode 100644 index 176ac1ae43..0000000000 --- a/.github/workflows/oracle-evidence-audit.yml +++ /dev/null @@ -1,177 +0,0 @@ -name: Oracle evidence audit - -on: - workflow_dispatch: - inputs: - previous_release_tag: - description: Optional Oracle evidence release tag to use instead of the newest registry release - required: false - type: string - -permissions: - contents: read - -concurrency: - group: oracle-evidence-audit - cancel-in-progress: false - -env: - HARBOR_VERSION: 0.13.2 - TERMINAL_BENCH_REVISION: d49e28f1e4ddd13d289e85a5f312a66750951932 - -jobs: - prepare: - runs-on: ubuntu-latest - outputs: - matrix: ${{ steps.plan.outputs.matrix }} - has_misses: ${{ steps.plan.outputs.has_misses }} - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 - with: - node-version: '24' - cache: npm - - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0 - - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0 - - run: npm ci - - run: npm run build:test - - name: Install pinned Harbor - run: | - uv tool install "harbor==${HARBOR_VERSION}" - uv tool dir --bin >> "$GITHUB_PATH" - - name: Check out frozen Terminal-Bench 2.1 tasks - run: | - git clone --filter=blob:none https://github.com/harbor-framework/terminal-bench-2-1.git "$RUNNER_TEMP/terminal-bench-2-1" - git -C "$RUNNER_TEMP/terminal-bench-2-1" checkout "$TERMINAL_BENCH_REVISION" - - name: Download previous registry snapshot - id: previous - env: - GH_TOKEN: ${{ github.token }} - REQUESTED_TAG: ${{ inputs.previous_release_tag }} - run: | - tag="$REQUESTED_TAG" - if [[ -z "$tag" ]]; then - tag="$(gh release list --limit 100 --json tagName,createdAt --jq '[.[] | select(.tagName | startswith("oracle-evidence-"))] | sort_by(.createdAt) | last | .tagName // ""')" - fi - if [[ -n "$tag" ]]; then - gh release download "$tag" --pattern oracle-registry.json --output "$RUNNER_TEMP/previous-oracle-registry.json" - echo "path=$RUNNER_TEMP/previous-oracle-registry.json" >> "$GITHUB_OUTPUT" - fi - - name: Plan incremental audit - id: plan - run: | - args=( - plan - --tasks-root "$RUNNER_TEMP/terminal-bench-2-1/tasks" - --out "$RUNNER_TEMP/oracle-plan/plan.json" - --matrix-out "$RUNNER_TEMP/oracle-plan/matrix.json" - ) - if [[ -n "${{ steps.previous.outputs.path }}" ]]; then - args+=(--previous "${{ steps.previous.outputs.path }}") - fi - node packages/headless/harbor/run-oracle-registry-audit.mjs "${args[@]}" - matrix="$(jq -c . "$RUNNER_TEMP/oracle-plan/matrix.json")" - count="$(jq '.include | length' "$RUNNER_TEMP/oracle-plan/matrix.json")" - echo "matrix=$matrix" >> "$GITHUB_OUTPUT" - [[ "$count" -gt 0 ]] && echo "has_misses=true" >> "$GITHUB_OUTPUT" || echo "has_misses=false" >> "$GITHUB_OUTPUT" - - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: oracle-audit-plan - path: ${{ runner.temp }}/oracle-plan/plan.json - retention-days: 7 - - audit: - needs: prepare - if: needs.prepare.outputs.has_misses == 'true' - runs-on: ubuntu-latest - strategy: - fail-fast: false - max-parallel: 6 - matrix: ${{ fromJSON(needs.prepare.outputs.matrix) }} - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 - with: - node-version: '24' - cache: npm - - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0 - - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0 - - run: npm ci - - run: npm run build:test - - name: Install pinned Harbor - run: | - uv tool install "harbor==${HARBOR_VERSION}" - uv tool dir --bin >> "$GITHUB_PATH" - - name: Check out frozen Terminal-Bench 2.1 tasks - run: | - git clone --filter=blob:none https://github.com/harbor-framework/terminal-bench-2-1.git "$RUNNER_TEMP/terminal-bench-2-1" - git -C "$RUNNER_TEMP/terminal-bench-2-1" checkout "$TERMINAL_BENCH_REVISION" - - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 - with: - name: oracle-audit-plan - path: ${{ runner.temp }}/oracle-plan - - name: Audit ${{ matrix.task_id }} - run: | - node packages/headless/harbor/run-oracle-registry-audit.mjs task \ - --plan "$RUNNER_TEMP/oracle-plan/plan.json" \ - --tasks-root "$RUNNER_TEMP/terminal-bench-2-1/tasks" \ - --task-id "${{ matrix.task_id }}" \ - --jobs-dir "$RUNNER_TEMP/oracle-jobs" \ - --out "$RUNNER_TEMP/oracle-entry/${{ matrix.task_id }}.json" - - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: oracle-entry-${{ matrix.task_id }} - path: ${{ runner.temp }}/oracle-entry/${{ matrix.task_id }}.json - retention-days: 7 - - publish: - needs: [prepare, audit] - if: always() && needs.prepare.result == 'success' && (needs.audit.result == 'success' || needs.audit.result == 'skipped') - runs-on: ubuntu-latest - permissions: - contents: write - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 - with: - node-version: '24' - cache: npm - - run: npm ci - - run: npm run build:test - - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 - with: - name: oracle-audit-plan - path: ${{ runner.temp }}/oracle-plan - - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 - if: needs.prepare.outputs.has_misses == 'true' - with: - pattern: oracle-entry-* - path: ${{ runner.temp }}/oracle-entries - merge-multiple: true - - name: Merge immutable evidence - run: | - node packages/headless/harbor/run-oracle-registry-audit.mjs merge \ - --plan "$RUNNER_TEMP/oracle-plan/plan.json" \ - --entries-dir "$RUNNER_TEMP/oracle-entries" \ - --out "$RUNNER_TEMP/oracle-release/oracle-registry.json" \ - --evidence-out "$RUNNER_TEMP/oracle-release/oracle-evidence.jsonl" - - name: Publish append-only registry release - env: - GH_TOKEN: ${{ github.token }} - run: | - fingerprint="$(jq -r .fingerprint "$RUNNER_TEMP/oracle-release/oracle-registry.json")" - tag="oracle-evidence-${fingerprint#sha256:}" - if gh release view "$tag" >/dev/null 2>&1; then - echo "release $tag already exists; refusing to overwrite" >&2 - exit 1 - fi - gh release create "$tag" \ - "$RUNNER_TEMP/oracle-release/oracle-registry.json" \ - "$RUNNER_TEMP/oracle-release/oracle-evidence.jsonl" \ - --target "$GITHUB_SHA" \ - --title "Oracle evidence ${fingerprint#sha256:}" \ - --notes "Controlled Terminal-Bench 2.1 Oracle audit from workflow run $GITHUB_RUN_ID. Snapshot: $fingerprint" \ - --prerelease \ - --latest=false - echo "Oracle registry: https://github.com/$GITHUB_REPOSITORY/releases/download/$tag/oracle-registry.json" >> "$GITHUB_STEP_SUMMARY" - echo "Snapshot fingerprint: $fingerprint" >> "$GITHUB_STEP_SUMMARY" diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 42e166cf5d..cb9adb49e1 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -2,135 +2,64 @@ # Maka Backend Architecture -> This is the entry point for Maka Agent backend architecture. It does not repeat each deep-dive article. It establishes the system spine and helps readers reach the right chapter by engineering question. The current series covers Runtime, tools and context, durable Headless tasks, Self-check, the AHE self-iteration boundary, Graph scheduling over child Sessions, and crash-safe Runtime continuation. - -## Architecture in one sentence - -Maka is a **log-first, projection-driven** Agent Runtime. Execution facts enter append-only logs; Session state, model context, TaskRun, Self-check, and evolution evidence are projections of those facts for different consumers. +Maka has one execution authority: Runtime Host. Desktop, TUI, CLI, bots, and evaluation clients ask Runtime Host to execute work; none owns a second Runtime. ```mermaid flowchart LR - U["Desktop / CLI / Bot"] --> S["SessionManager"] + C["Desktop / TUI / CLI / Bot"] --> H["Runtime Host"] + H --> S["SessionManager"] S --> R["AgentRun + Runtime Runner"] R --> T["Tool Runtime"] R --> L["Runtime Event Log"] - R --> H["Headless Task Event Log"] - T --> L S --> G["Agent Graph Control Plane"] G --> R + L --> P["Context / Session / UI / Recovery projections"] - L --> C["Provider Context Projection"] - L --> V["Session / UI Read Models"] - L --> X["Crash Recovery / Continuation"] - L --> GP["Graph Records / Client Projection"] - GP --> G - L -. "trajectory refs" .-> H - - H --> P["TaskRun Projection"] - P --> K["Bounded Self-check"] - P --> E["AHE Evidence Export"] - E --> A["External Evolution Loop"] + E["@maka/eval\nExperiment → Cells → Attempts → Results"] --> H + X["External subjects"] --> E ``` -Read left to right. Entry points hand user intent to Runtime; model and tool execution produce facts; those facts are projected into model context, interactive views, crash-recovery decisions, Graph scheduling inputs, durable task state, and evolution evidence. Graph coordinates child Sessions from durable schedule metadata but sends execution back through the same Runtime. Providers, concrete storage implementations, and UI components are omitted so the diagram can preserve the backend spine shared by this series. - -## A four-layer mental model - -### 1. Execution facts - -An Agent Run produces model messages, Tool Calls, Tool Results, permission decisions, and termination facts. Runtime Event Log is the canonical source for those interaction semantics except hosted permission answers: InteractionStore is their canonical authority, while the Runtime ledger stores only answer identity and audit facts. The embedded/legacy path retains its existing decision-event semantics. Context pruning and Compaction may change what the model sees next, but cannot rewrite facts that already occurred. - -Relevant chapters: 1, 2, 3, and 8. - -### 2. Coordinated Agent work - -When dependent Agent work benefits from dynamic topology, Graph treats child Sessions as operator containers, Session-inline AgentRuns as activations, and committed RuntimeEvents as reference-only records. SQLite owns schedule, topology, admission, and supervisor-wake metadata; Runtime keeps execution authority. The main Agent stays beside the graph to observe, intervene, and synthesize without gating normal record delivery. - -Relevant chapter: 7. - -### 3. Durable tasks - -When a task outlives one Turn or process, Headless uses an independent task identity, Task Event Log, and TaskRun projection to preserve progress across Attempts. Self-check provides bounded feedback inside that task loop but does not own final fact authority. - -Relevant chapters: 4 and 5. - -### 4. Evolution - -AHE organizes outcomes and traces from multiple TaskRuns into evolution evidence bound to target identity. It remains outside the interactive Runtime and advances system changes through a constrained change surface, falsifiable manifests, candidate evaluation, and rollback lineage. - -Relevant chapter: 6. - -## Eight-chapter index - -| Chapter | Core question | Implementation status | Read | -|---|---|---|---| -| 1. Log Is the Runtime | How does Maka preserve and replay the state space of an Agent Run? | Current | [English](./docs/architecture/runtime-core-architecture-draft.md) · [中文](./docs/architecture/runtime-core-architecture-draft.zh-CN.md) | -| 2. Evidence Before Compression | How can a large Tool Result leave Turn-level evidence without exhausting active context? | Current + Target | [English](./docs/architecture/turn-evidence-tools-active-prune-draft.md) · [中文](./docs/architecture/turn-evidence-tools-active-prune-draft.zh-CN.md) | -| 3. Compaction Is a Projection | How can the LLM forget old context without losing historical facts? | Current | [English](./docs/architecture/llm-compaction-events-log-projection-draft.md) · [中文](./docs/architecture/llm-compaction-events-log-projection-draft.zh-CN.md) | -| 4. The Durable Task Loop | How does Maka continue a task that outlives a Turn, Run, or process? | Current + Target | [English](./docs/architecture/durable-task-loop-headless-draft.md) · [中文](./docs/architecture/durable-task-loop-headless-draft.zh-CN.md) | -| 5. Self-Check Is Not Self-Trust | How can an Agent inspect and repair its work without turning self-report into authority? | Current + Target | [English](./docs/architecture/self-check-bounded-feedback-loop-draft.md) · [中文](./docs/architecture/self-check-bounded-feedback-loop-draft.zh-CN.md) | -| 6. Self-Iteration Happens Outside the Runtime | How does Maka turn run experience into falsifiable and reversible system improvement? | Current + Target | [English](./docs/architecture/ahe-self-iteration-boundary-draft.md) · [中文](./docs/architecture/ahe-self-iteration-boundary-draft.zh-CN.md) | -| 7. Graph Is a Schedule, Not a Second Runtime | How does Maka coordinate dynamic dependent Agent work while the main Agent supervises beside the data path? | Current | [English](./docs/architecture/agent-graph-stream-scheduling-draft.md) · [中文](./docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md) | -| 8. Resume Is Not Retry | How does Maka recover crash facts, avoid duplicate side effects, and create a provably safe new execution? | Current + Target | [English](./docs/architecture/runtime-resume-architecture.md) · [中文](./docs/architecture/runtime-resume-architecture.zh-CN.md) | +Runtime Host owns Session and Turn identity, agent lifecycle, continuation, tools, permissions, and events. `@maka/eval` owns benchmark experiment semantics only: subjects, tasks, repetitions, cells, immutable attempts, result selection, budgets, and verifier configuration. A Maka subject always crosses the public Runtime Host client/protocol boundary; an external competitor is a generic external subject. -**Current + Target** means the article covers verified implementation and visibly labeled target direction. It does not mean Target sections are implemented. The `implementation_status` and `last_verified` fields in each article's front matter are the more precise status source. +## Runtime layers -## Choose a reading path by problem +1. Runtime Event Log is the canonical source for model messages, tool calls, tool results, and termination facts. Context pruning and compaction change provider input projections, not history. +2. SessionManager and AgentRun own execution lifecycle. Runtime Host owns admission, client capabilities, interactions, and the public protocol. +3. Agent Graph schedules dependent work using child Sessions and sends every activation back through the same Runtime. +4. Storage owns interactive Runtime state. It has no Eval-specific root, TaskRun ledger, or experiment result authority. -### Entering Runtime for the first time +## Eval boundary -Read `1 → 2 → 3 → 8`. Start with the fact log, then learn the tool-evidence and context projections that recovery later consumes. Finish with crash repair and safe continuation. +```text +Experiment = benchmark + executor + subjects + tasks + repetitions +Cell = task × repetition × subject -### Changing Tools, Context, or Compaction - -Read `1` for the canonical-fact boundary, then `2 → 3`. Add `8` when the change affects T1/T2, recovery, or continuation, and add `4` when it affects evidence consumed by durable tasks. - -### Changing crash recovery, durable Tool boundaries, or workspace continuity - -Read `1 → 8`. Chapter 1 establishes RuntimeEvent and AgentRun authority; Chapter 8 explains startup repair, T1/T2, RecoveryResolver, safe-boundary continuation, and the Phase 3–4 workspace path. Add `4` for Headless Attempt recovery and `7` when recovery affects Graph activations or supervisor wakes. - -### Changing Headless or task recovery - -Read `1 → 8 → 4 → 5`. Chapter 8 separates Runtime continuation from Attempt retry and workspace restore. Chapter 3 adds context recovery, while Chapter 2 adds the Tool Result evidence boundary. - -### Changing Self-check or completion conditions - -Read `4 → 5`, then revisit Chapter 2's rule that context pruning must not delete evidence. - -### Changing AHE or self-iteration - -Read `1 → 4 → 5 → 6`. Chapter 6 depends on the Event Log, TaskRun projection, and authority boundaries established earlier. +repetition = a new experimental sample +infra retry = a replacement attempt for the same cell +continuation = internal Runtime Host behavior within a Maka subject +``` -### Changing Graph, child Sessions, or multi-Agent scheduling +One Experiment uses one fully expanded declarative spec. Every arm shares its executor, benchmark, tasks, budget, and verifier. A/B is simply a two-arm Experiment. Harbor and Pier are executor adapters, not independent workflows. -Read `1 → 7`. Chapter 1 establishes RuntimeEvent and AgentRun authority; Chapter 7 explains how Graph projects those facts into records, binds operators to child Sessions, linearizes schedule and admission in SQLite, and returns control to the root supervisor Agent. Add `2 → 3` when changing how child output is retrieved or compacted. +The result kernel contains only score, normalized usage, attributable cost, duration, status or failure reason, and artifacts. When a cell has multiple attempts, the earliest valid attempt is authoritative; operators cannot choose a preferred outcome. ## Code boundaries -| Area | Primary responsibility | +| Area | Responsibility | |---|---| -| `packages/core` | Pure contracts for Session, Runtime Event, AgentRun, and permission | -| `packages/storage` | Durable stores for sessions, settings, run ledgers, and the SQLite metadata control plane | -| `packages/runtime` | SessionManager, AgentRun, model adapters, tool execution, context, recovery, and Graph reconciliation | -| `packages/headless` | TaskRun, Autonomous Loop, Self-check, result export, and AHE protocol | -| `apps/desktop/src/main` | Electron main-process composition, IPC, and product-entry adapters | - -The “code map” in each deep-dive article is the preferred implementation entry point. Earlier design and evolution material remains available in: - -- [`docs/archive/runtime-kernel.md`](./docs/archive/runtime-kernel.md) -- [`docs/archive/runtime-v2-architecture-evolution.md`](./docs/archive/runtime-v2-architecture-evolution.md) -- [`docs/archive/runtime-v2-implementation-notes.md`](./docs/archive/runtime-v2-implementation-notes.md) - -Those documents provide historical design context and implementation notes. The eight chapters indexed here are the narrative entry point for current backend mechanisms. - -## Documentation layout - -`docs/architecture/` remains flat. One mechanism owns one stable slug: the default `.md` file is English and `.zh-CN.md` is its Chinese counterpart. While the collection is still easy to scan, avoiding another `chapters/` level keeps links shallow. - -Maintenance rules: - -- Every new deep dive needs a stable `doc_id`, implementation status, verification date, and owner; -- Chinese and English counterparts must preserve scope, Current/Target boundaries, diagrams, and limitations; -- This index stores one-sentence questions and links; mechanism details remain in the deep dives; -- Adding, renaming, or publishing an article requires updating both architecture indexes; -- The `-draft` filename suffix must agree with front matter `document_status`; publication should remove the suffix and update all index links in the same change. +| `packages/core` | Pure Session, Runtime Event, AgentRun, permission, and protocol contracts | +| `packages/storage` | Interactive Runtime stores and SQLite control planes | +| `packages/runtime` | SessionManager, AgentRun, model adapters, tools, context, recovery, and Graph reconciliation | +| `packages/runtime-host` | Sole hosted execution authority and public client/protocol | +| `packages/eval` | Experiment cells, attempts, result selection, and subject/executor adapters | +| `packages/cli` | TUI, `maka run`, and the public `maka eval` route | +| `apps/desktop/src/main` | Electron composition and product-entry adapters | + +## Reading paths + +- Runtime facts and projections: [Runtime core](./docs/architecture/runtime-core-architecture-draft.md) and [compaction](./docs/architecture/llm-compaction-events-log-projection-draft.md). +- Crash recovery and continuation: [Runtime resume](./docs/architecture/runtime-resume-architecture.md). +- Multi-agent scheduling: [Agent Graph](./docs/architecture/agent-graph-stream-scheduling-draft.md). +- Evaluation behavior and public seams: [`packages/eval`](./packages/eval). + +Historical designs remain under [`docs/archive`](./docs/archive/README.md). Current GitHub issues and source take precedence over older drafts. diff --git a/ARCHITECTURE.zh-CN.md b/ARCHITECTURE.zh-CN.md index 4af655d4fc..0083347798 100644 --- a/ARCHITECTURE.zh-CN.md +++ b/ARCHITECTURE.zh-CN.md @@ -1,136 +1,65 @@ [ENGLISH](./ARCHITECTURE.md) -# Maka Backend Architecture +# Maka 后端架构 -> 这是 Maka Agent 后端架构的总入口。它不重复每篇专题文章，而是先给出系统主线，再帮助读者按问题快速找到对应章节。当前系列聚焦 Runtime、工具与上下文、Headless 长程任务、Self-check、AHE 自迭代边界、建立在 child Session 之上的 Graph 调度，以及 crash-safe Runtime continuation。 - -## 一句话架构 - -Maka 是一个 **log-first、projection-driven** 的 Agent Runtime：运行事实进入 append-only log；Session、模型上下文、TaskRun、Self-check 和演化证据都是这些事实面向不同消费者的投影。 +Maka 只有一个执行 authority：Runtime Host。Desktop、TUI、CLI、bot 和 Eval client 都请求 Runtime Host 执行工作，不再拥有第二套 Runtime。 ```mermaid flowchart LR - U["Desktop / CLI / Bot"] --> S["SessionManager"] + C["Desktop / TUI / CLI / Bot"] --> H["Runtime Host"] + H --> S["SessionManager"] S --> R["AgentRun + Runtime Runner"] R --> T["Tool Runtime"] R --> L["Runtime Event Log"] - R --> H["Headless Task Event Log"] - T --> L S --> G["Agent Graph Control Plane"] G --> R + L --> P["Context / Session / UI / Recovery projections"] - L --> C["Provider Context Projection"] - L --> V["Session / UI Read Models"] - L --> X["Crash Recovery / Continuation"] - L --> GP["Graph Records / Client Projection"] - GP --> G - L -. "trajectory refs" .-> H - - H --> P["TaskRun Projection"] - P --> K["Bounded Self-check"] - P --> E["AHE Evidence Export"] - E --> A["External Evolution Loop"] + E["@maka/eval\nExperiment → Cells → Attempts → Results"] --> H + X["External subjects"] --> E ``` -从左向右读：入口把用户意图交给 Runtime；模型和工具执行产生事实；同一组事实随后被投影成模型上下文、交互界面、崩溃恢复判定、Graph 调度输入、长程任务状态和演化证据。Graph 从持久 schedule metadata 协调 child Session，但执行仍回到同一套 Runtime。图中省略了 provider、具体存储实现和 UI 组件，只保留本系列文档共同解释的后端主线。 - -## 四层心智模型 - -### 1. 运行事实层 - -一次 Agent Run 产生模型消息、Tool Call、Tool Result、权限和终止事实。除 hosted permission answer 外，Runtime Event Log 是这些交互语义的 canonical source；hosted permission answer 以 InteractionStore 为 canonical authority，Runtime ledger 只保存 answer identity 与 audit fact。embedded/legacy 路径保留既有的 decision-event 语义。上下文裁剪与 Compaction 可以改变模型下一次看到什么，但不能反向改写已经发生的事实。 - -对应章节：第一章、第二章、第三章、第八章。 - -### 2. Agent work 协调层 - -当相互依赖的 Agent work 需要动态 topology 时，Graph 把 child Session 视为 operator 容器，把 Session-inline AgentRun 视为 activation，把已提交 RuntimeEvent 视为 reference-only record。SQLite 拥有 schedule、topology、admission 与 supervisor wake metadata，Runtime 继续拥有 execution authority。主 Agent 始终在图旁观察、干预和综合，但不阻塞正常 record delivery。 - -对应章节：第七章。 - -### 3. 长程任务层 - -当任务长于一次 Turn 或一个进程时，Headless 通过独立的 Task identity、Task Event Log 和 TaskRun projection 保存跨 Attempt 的进度。Self-check 在这个任务循环内提供一次受限反馈，但不拥有最终事实 authority。 - -对应章节：第四章、第五章。 - -### 4. 演化层 - -AHE 把多次 TaskRun 的结果和 trace 组织成带 target identity 的演化证据。它位于交互 Runtime 外部，通过受限 change surface、可证伪 manifest、candidate evaluation 和 rollback lineage 推进系统改进。 - -对应章节：第六章。 - -## 八章索引 - -| 章节 | 核心问题 | 实现状态 | 阅读 | -|---|---|---|---| -| 1. Log Is the Runtime | Maka 如何保存并回放一次 Agent Run 的状态空间？ | Current | [中文](./docs/architecture/runtime-core-architecture-draft.zh-CN.md) · [English](./docs/architecture/runtime-core-architecture-draft.md) | -| 2. Evidence Before Compression | 巨大的 Tool Result 如何留下 Turn 级证据，又不拖垮当前上下文？ | Current + Target | [中文](./docs/architecture/turn-evidence-tools-active-prune-draft.zh-CN.md) · [English](./docs/architecture/turn-evidence-tools-active-prune-draft.md) | -| 3. Compaction Is a Projection | LLM 如何忘记旧上下文，同时不丢失历史事实？ | Current | [中文](./docs/architecture/llm-compaction-events-log-projection-draft.zh-CN.md) · [English](./docs/architecture/llm-compaction-events-log-projection-draft.md) | -| 4. The Durable Task Loop | 一个任务长于 Turn、Run 和进程时，Maka 如何持续推进？ | Current + Target | [中文](./docs/architecture/durable-task-loop-headless-draft.zh-CN.md) · [English](./docs/architecture/durable-task-loop-headless-draft.md) | -| 5. Self-Check Is Not Self-Trust | Agent 如何检查和修复自己的工作，而不把自述变成 authority？ | Current + Target | [中文](./docs/architecture/self-check-bounded-feedback-loop-draft.zh-CN.md) · [English](./docs/architecture/self-check-bounded-feedback-loop-draft.md) | -| 6. Self-Iteration Happens Outside the Runtime | Maka 如何把运行经验变成可证伪、可回滚的系统改进？ | Current + Target | [中文](./docs/architecture/ahe-self-iteration-boundary-draft.zh-CN.md) · [English](./docs/architecture/ahe-self-iteration-boundary-draft.md) | -| 7. Graph Is a Schedule, Not a Second Runtime | Maka 如何协调动态依赖的 Agent work，同时让主 Agent 始终在 data path 旁监督？ | Current | [中文](./docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md) · [English](./docs/architecture/agent-graph-stream-scheduling-draft.md) | -| 8. Resume Is Not Retry | Maka 如何恢复 crash facts、避免重复副作用，并建立一个可证明安全的新执行？ | Current + Target | [中文](./docs/architecture/runtime-resume-architecture.zh-CN.md) · [English](./docs/architecture/runtime-resume-architecture.md) | +Runtime Host 拥有 Session 和 Turn identity、agent lifecycle、continuation、tools、permissions 与 events。`@maka/eval` 只拥有 benchmark 实验语义：subjects、tasks、repetitions、cells、immutable attempts、result selection、budget 和 verifier 配置。Maka subject 必须经过公开的 Runtime Host client/protocol 边界；外部竞品是 generic external subject。 -这里的 **Current + Target** 表示文章同时记录已验证实现与明确标注的目标方向，不表示 Target 部分已经落地。每篇文章 front matter 中的 `implementation_status` 和 `last_verified` 是更细的状态来源。 +## Runtime 分层 -## 按问题选择阅读路径 +1. Runtime Event Log 是模型消息、Tool Call、Tool Result 和终止事实的 canonical source。上下文裁剪与 compaction 只改变 provider input projection，不改写历史。 +2. SessionManager 和 AgentRun 拥有执行生命周期。Runtime Host 拥有 admission、client capability、interaction 与公开协议。 +3. Agent Graph 通过 child Session 调度依赖工作，并把每次 activation 送回同一 Runtime。 +4. Storage 只拥有交互 Runtime 状态，不再有 Eval 专用 root、TaskRun ledger 或实验结果 authority。 -### 第一次进入 Runtime +## Eval 边界 -按 `1 → 2 → 3 → 8` 阅读。先理解事实日志，再理解恢复会消费的工具证据和上下文投影，最后进入崩溃修复与安全续跑。 +```text +Experiment = benchmark + executor + subjects + tasks + repetitions +Cell = task × repetition × subject -### 修改 Tool、Context 或 Compaction - -先读 `1` 建立 canonical fact 边界，再读 `2 → 3`。如果改动涉及 T1/T2、恢复或 continuation，再补 `8`；如果影响长程任务的证据消费，再补 `4`。 - -### 修改 crash recovery、durable Tool boundary 或 workspace continuity - -按 `1 → 8` 阅读。第一章建立 RuntimeEvent 与 AgentRun authority；第八章解释 startup repair、T1/T2、RecoveryResolver、safe-boundary continuation 和 Phase 3–4 workspace 路线。如果涉及 Headless Attempt recovery，再补 `4`；如果恢复会影响 Graph activation 或 supervisor wake，再补 `7`。 - -### 修改 Headless 或任务恢复 - -按 `1 → 8 → 4 → 5` 阅读。第八章区分 Runtime continuation、Attempt retry 和 workspace restore；第四章解释 durability，第三章可以补充上下文恢复，第二章可以补充 Tool Result 的证据边界。 - -### 修改 Self-check 或完成条件 - -按 `4 → 5` 阅读，再回看 `2` 中“证据不能被上下文裁剪删除”的原则。 - -### 修改 AHE 或自迭代流程 - -按 `1 → 4 → 5 → 6` 阅读。第六章依赖前面建立的 Event Log、TaskRun projection 和 authority 边界。 +repetition = 新的实验样本 +infra retry = 同一个 cell 的替换 attempt +continuation = Maka subject 内部的 Runtime Host 行为 +``` -### 修改 Graph、child Session 或 multi-Agent scheduling +一个 Experiment 使用一份完全展开的声明式 spec。所有 arms 共享 executor、benchmark、tasks、budget 和 verifier。A/B 只是双臂 Experiment。Harbor 和 Pier 是 executor adapter，不是独立 workflow。 -按 `1 → 7` 阅读。第一章建立 RuntimeEvent 与 AgentRun authority；第七章解释 Graph 如何把这些事实投影成 record、把 operator 绑定到 child Session、在 SQLite 中 linearize schedule 与 admission，并把控制权交还 root supervisor Agent。如果改动涉及 child output 的读取或 compaction，再补 `2 → 3`。 +通用结果只包含 score、normalized usage、可归因 cost、duration、status 或 failure reason 以及 artifacts。一个 cell 有多个 attempts 时，以最早有效 attempt 为权威，operator 不能人工挑选结果。 ## 代码边界 -| 区域 | 主要职责 | +| 区域 | 职责 | |---|---| -| `packages/core` | Session、Runtime Event、AgentRun、permission 等纯 contract | -| `packages/storage` | Session、settings、run ledger 与 SQLite metadata control plane 等持久 store | -| `packages/runtime` | SessionManager、AgentRun、模型适配、工具执行、上下文、恢复与 Graph reconciliation | -| `packages/headless` | TaskRun、Autonomous Loop、Self-check、结果导出与 AHE protocol | -| `apps/desktop/src/main` | Electron main-process composition、IPC 与产品入口适配 | - -专题文章中的“代码地图”是定位实现的首选入口。更早的设计和演进材料仍保留在： - -- [`docs/archive/runtime-kernel.md`](./docs/archive/runtime-kernel.md) -- [`docs/archive/runtime-v2-architecture-evolution.md`](./docs/archive/runtime-v2-architecture-evolution.md) -- [`docs/archive/runtime-v2-implementation-notes.md`](./docs/archive/runtime-v2-implementation-notes.md) - -这些文档提供历史设计背景和实现笔记；本页索引的八章是当前后端机制的叙事入口。 - -## 文档目录约定 - -`docs/architecture/` 当前保持扁平结构：一项机制对应一个稳定 slug，默认 `.md` 为英文，`.zh-CN.md` 为中文。在专题数量仍可快速浏览时，不增加 `chapters/` 层级，避免链接无谓变深。 - -维护规则： - -- 新专题必须有稳定 `doc_id`、实现状态、验证日期和 owner； -- 中英文 counterpart 必须保持 scope、Current/Target 边界、图表和限制一致； -- 本页只保存一句话问题和入口，机制细节留在专题文章中； -- 新增、重命名或发布专题时，同时更新中英文总索引； -- 文件名中的 `-draft` 与 front matter 的 `document_status` 一致；正式发布时应在同一次变更中移除该后缀并修正所有索引链接。 +| `packages/core` | Session、Runtime Event、AgentRun、permission 和协议等纯 contract | +| `packages/storage` | 交互 Runtime store 与 SQLite control plane | +| `packages/runtime` | SessionManager、AgentRun、模型 adapter、tools、context、recovery 与 Graph reconciliation | +| `packages/runtime-host` | 唯一 hosted execution authority 与公开 client/protocol | +| `packages/eval` | Experiment cell、attempt、result selection 与 subject/executor adapter | +| `packages/cli` | TUI、`maka run` 与唯一公开 `maka eval` 路由 | +| `apps/desktop/src/main` | Electron composition 与产品入口 adapter | + +## 阅读路径 + +- Runtime 事实与 projection：[Runtime core](./docs/architecture/runtime-core-architecture-draft.zh-CN.md) 与 [compaction](./docs/architecture/llm-compaction-events-log-projection-draft.zh-CN.md)。 +- Crash recovery 与 continuation：[Runtime resume](./docs/architecture/runtime-resume-architecture.zh-CN.md)。 +- Multi-agent scheduling：[Agent Graph](./docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md)。 +- Eval 行为与公开 seam：[`packages/eval`](./packages/eval)。 + +历史设计保存在 [`docs/archive`](./docs/archive/README.md)。当前 GitHub Issue 与源码优先于旧 draft。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60f605d11a..52ad8deb69 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,7 +67,7 @@ npm --workspace maka-agent exec -- maka # TUI npm --workspace maka-agent exec -- maka run "…" # one non-interactive turn ``` -Headless commands live in [`packages/headless/README.md`](./packages/headless/README.md). +Evaluation commands and contracts live in [`packages/eval`](./packages/eval). ### Building @@ -75,7 +75,7 @@ Headless commands live in [`packages/headless/README.md`](./packages/headless/RE ``` code-mode → core → storage → mcp → runtime → runtime-host - → computer-use → headless → maka-agent → ui → desktop + → computer-use → eval → maka-agent → ui → desktop ``` Building one workspace only succeeds when its dependencies are already built — @@ -155,7 +155,7 @@ the required sections and the checklist. Fill it in rather than replacing it. ``` `` is the set in [branch naming](#branch-naming). `` is the -workspace or area — `desktop`, `ui`, `runtime`, `headless`, `settings`, +workspace or area — `desktop`, `ui`, `runtime`, `eval`, `settings`, `runtime-host`, `storage`, `core`, `cli`, `deps`, `computer-use`, `scripts`, `release`, `windows`, `e2e`, `security`, and so on — `git log` shows the set in use. diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md index b16de01ef1..e7b67725c0 100644 --- a/CONTRIBUTING.zh-CN.md +++ b/CONTRIBUTING.zh-CN.md @@ -63,7 +63,7 @@ npm --workspace maka-agent exec -- maka # TUI npm --workspace maka-agent exec -- maka run "…" # 非交互地跑一个 Turn ``` -Headless 的命令见 [`packages/headless/README.md`](./packages/headless/README.md)。 +Eval 的命令与 contract 见 [`packages/eval`](./packages/eval)。 ### 构建 @@ -71,7 +71,7 @@ Headless 的命令见 [`packages/headless/README.md`](./packages/headless/README ``` code-mode → core → storage → mcp → runtime → runtime-host - → computer-use → headless → maka-agent → ui → desktop + → computer-use → eval → maka-agent → ui → desktop ``` 只有依赖都已构建好时，单独构建某个 workspace 才会成功——拿过期的 `@maka/core` 去编译 `@maka/runtime`，产生的类型错误看起来会像是你刚写的代码有问题。拿不准就从根目录构建。 @@ -142,7 +142,7 @@ CI 里名为 `typecheck` 的 job 会在 `bash -e` 下跑完上面全部命令， (): ``` -`` 就是[分支命名](#分支命名)那一套。`` 是改动的 workspace 或区域——`desktop`、`ui`、`runtime`、`headless`、`settings`、`runtime-host`、`storage`、`core`、`cli`、`deps`、`computer-use`、`scripts`、`release`、`windows`、`e2e`、`security` 等——`git log` 里能看到实际在用的集合。 +`` 就是[分支命名](#分支命名)那一套。`` 是改动的 workspace 或区域——`desktop`、`ui`、`runtime`、`eval`、`settings`、`runtime-host`、`storage`、`core`、`cli`、`deps`、`computer-use`、`scripts`、`release`、`windows`、`e2e`、`security` 等——`git log` 里能看到实际在用的集合。 ``` fix(desktop): classify provider action errors from the unwrapped IPC message diff --git a/README.md b/README.md index 982916c416..92568d28b7 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ **A local-first Agent workspace built for real work.** -Maka does more than answer questions. With controlled permissions, it can inspect projects, execute tools, produce artifacts, and preserve model messages, tool calls, and durable-task progress as recoverable execution facts. Desktop, the terminal TUI, and the non-interactive CLI are clients of one per-workspace Runtime Host. Headless owns a separate task runtime for durable evaluation and automation workloads. +Maka does more than answer questions. With controlled permissions, it can inspect projects, execute tools, produce artifacts, and preserve model messages and tool calls as recoverable execution facts. Desktop, the terminal TUI, the non-interactive CLI, and Maka evaluation subjects all execute through Runtime Host. > [!IMPORTANT] > Maka is under active development. The macOS Apple Silicon desktop build is an early public release; data formats, CLI commands, and experimental capabilities may still change. @@ -18,8 +18,7 @@ Maka does more than answer questions. With controlled permissions, it can inspec - **Local-first instead of hosted-first**: sessions, settings, and run records stay on your machine by default. You choose the model connection: cloud API, local model, or compatible gateway. - **Log is the Runtime**: model messages, Tool Calls, Tool Results, and termination facts enter Runtime Event Log. Sessions, UI, model context, and recovery are projections over that log. - **Context is not history**: Tool Result pruning and LLM Compaction change what the next inference sees without treating recorded evidence as disposable context. -- **A task may outlive a Turn**: Headless uses TaskRun, Task Event Log, budgets, and continuation to advance interruptible and inspectable durable work. -- **Feedback is not fact authority**: Self-check may produce evidence and one bounded repair opportunity, but “I checked it” does not become a system fact. +- **One execution authority**: Runtime Host owns Session, Turn, agent lifecycle, continuation, tools, and events. Eval owns only experiment semantics and results. Read [Maka Backend Architecture](./ARCHITECTURE.md) for the complete design. @@ -29,7 +28,7 @@ Read [Maka Backend Architecture](./ARCHITECTURE.md) for the complete design. |---|---|---| | **Desktop** | Daily interaction, file and Artifact workflows, model and permission setup | Electron + React with streaming sessions, tool timelines, branching, search, and recovery | | **TUI / CLI** | Using Maka in the current project directory or running one non-interactive Turn | `maka`, `maka run`; shares workspace and model connections with Desktop | -| **Headless** | Durable tasks, recoverable TaskRuns, experiments, and evaluation | `maka eval` with task logs, export, resume, and comparison | +| **Eval** | Reproducible benchmark experiments across Maka and external subjects | `maka eval run --out ` | ## Current capabilities @@ -47,12 +46,12 @@ Read [Maka Backend Architecture](./ARCHITECTURE.md) for the complete design. - Local memory, web search, and bot entry points; - Integrations are configured independently, and not every experimental entry is available by default. -### Durable tasks and evolution +### Evaluation -- Append-only Task Event Log and TaskRun projection; -- Budgets, permission pauses, continuation, result export, and failed-task retry; -- Plan-first, source-guarded, and attempt-bounded Heavy-task Self-check; -- AHE target protocol and evidence export; complete automatic self-iteration remains an external or experimental workflow. +- Declarative multi-arm experiments expanded into task × repetition × subject cells; +- Immutable per-cell attempts with targeted infrastructure replacement and earliest-valid selection; +- A small result kernel for score, normalized usage, attributable cost, duration, status, failure reason, and artifacts; +- Maka subjects execute only through Runtime Host; external competitors use generic external subject adapters. ## Quick start @@ -128,7 +127,7 @@ The TUI also accepts `/graph on`, `/graph off`, and `/graph `. Non-interac supervisor output. Graph implementation operators use isolated Git worktrees, so the source project must be a clean Git worktree. -The CLI reads the same model connections and workspace configuration written by Desktop. See [`packages/headless/README.md`](./packages/headless/README.md) for Headless commands and its trust posture. +The CLI reads the same model connections and workspace configuration written by Desktop. Evaluation specs and adapters live in [`packages/eval`](./packages/eval). ## Architecture @@ -141,7 +140,9 @@ Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun ↓ Context / Session / UI projections -Headless / Eval → Task Event Log → TaskRun → Self-check / AHE evidence +Experiment → Cells → Attempts → Results + ↓ + Runtime Host executes Maka subjects ``` Start with [ARCHITECTURE.md](./ARCHITECTURE.md). It provides the system map, code boundaries, problem-oriented reading paths, and six bilingual deep dives. @@ -154,7 +155,7 @@ apps/desktop/ Electron main / preload / React renderer packages/core/ Pure contracts for Sessions, Events, Permissions, and Connections packages/storage/ SQLite operational state, configuration, and payload stores packages/runtime/ AgentRun, model adapters, tools, context, and recovery -packages/headless/ TaskRun, Autonomous Loop, Self-check, eval, and AHE +packages/eval/ Experiment cells, attempts, results, and executor/subject adapters packages/cli/ TUI and non-interactive CLI packages/ui/ Shared conversation, Markdown, Artifact, and UI primitives @@ -177,11 +178,11 @@ Maka stores workspace data under Electron `userData` by default: Current boundaries that matter: -- Sessions, messages, execution ledgers, workflows, usage, Automations, Daily Review, and Headless TaskRuns live in `runtime.sqlite`; +- Sessions, messages, execution ledgers, workflows, usage, Automations, and Daily Review live in `runtime.sqlite`; - Runtime credentials such as API keys, bot tokens, and proxy passwords currently live in local plaintext `credentials.json`, behind the OS account boundary, with POSIX directory mode `0700` and file mode `0600` enforced; -- Subscription OAuth tokens (Claude, Codex, GitHub Copilot, xAI, and the Antigravity preview) live in the same `credentials.json` — the single authority for desktop, TUI, and headless. Pre-existing Electron `safeStorage` credential/token files are not imported; affected users must re-authenticate; +- Subscription OAuth tokens (Claude, Codex, GitHub Copilot, xAI, and the Antigravity preview) live in the same `credentials.json` — the single authority for Runtime Host clients. Pre-existing Electron `safeStorage` credential/token files are not imported; affected users must re-authenticate; - Renderer does not receive plaintext credentials. File writes, Shell, and dangerous tool calls pass through the permission engine; -- Headless real-model evaluation fails closed by default and requires an explicit external isolation boundary. +- Eval does not construct Runtime or read Runtime storage. Maka subjects connect to an existing Runtime Host. Read [SECURITY.md](./SECURITY.md) for security reporting and policy, and [docs/README.md](./docs/README.md) for current privacy and sandbox contracts. @@ -190,7 +191,7 @@ Read [SECURITY.md](./SECURITY.md) for security reporting and policy, and [docs/R `runtime.sqlite` is the sole operational authority. It owns RuntimeEvents, session metadata and message history, Agent Graph control, core execution state, workflow state, usage and pricing, Artifact metadata, Automations, Daily Review, -and Headless TaskRuns. Artifact payload bytes remain regular files under +and Runtime continuation records. Artifact payload bytes remain regular files under `artifacts/`; connections, credentials, settings, MCP configuration, skills, and device identity remain configuration files. @@ -212,14 +213,6 @@ payload sizes against SQLite metadata before restore. Backup and restore use owner-only file modes, file and directory synchronization, staging, and atomic publication. -Headless trajectory hydration now consumes a frozen selected-session export -from that SQLite Artifact authority. The cell publishes `trajectory-state` -only when RuntimeEvents reference image Artifacts; Harbor downloads its -standalone `runtime.sqlite` first and then only the payloads referenced by the -validated snapshot. It does not copy a live WAL or fall back to -`artifacts/metadata.jsonl`. Missing, corrupt, unsupported, or mismatched -evidence fails closed to a summary trajectory instead of mixing authorities. - Runtime continuation remains opt-in: - `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` enables the Desktop interrupted-turn @@ -246,7 +239,7 @@ Run one workspace in isolation: ```sh npm --workspace @maka/runtime test -npm --workspace @maka/headless test +npm --workspace @maka/eval test npm --workspace @maka/desktop test ``` diff --git a/README.zh-CN.md b/README.zh-CN.md index 6bba86dcbf..c2c259e8ef 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -8,7 +8,7 @@ **一个为真实工作而生的本地优先 Agent 工作台。** -Maka 不只回答问题。它可以在受控权限下阅读项目、执行工具、生成产物，并把模型消息、工具调用和长程任务进度保存为可恢复的运行事实。桌面应用、终端 TUI 和非交互 CLI 共享每个工作区唯一的 Runtime Host；Headless 使用独立的任务 Runtime 承载持久评测和自动化工作负载。 +Maka 不只回答问题。它可以在受控权限下阅读项目、执行工具、生成产物，并把模型消息和工具调用保存为可恢复的运行事实。桌面应用、终端 TUI、非交互 CLI 和 Maka 评测 subject 都通过 Runtime Host 执行。 > [!IMPORTANT] > Maka 仍在活跃开发中。macOS Apple Silicon 桌面版是首个早期公开版本，数据格式、CLI 和实验能力仍可能变化。 @@ -18,8 +18,7 @@ Maka 不只回答问题。它可以在受控权限下阅读项目、执行工具 - **本地优先，而不是云端托管优先**：会话、设置和运行记录默认保存在本机；模型连接由你配置，可以使用云 API、本地模型或兼容网关。 - **Log is the Runtime**：模型消息、Tool Call、Tool Result 和终止事实进入 Runtime Event Log，Session、UI、模型上下文和恢复逻辑从日志生成投影。 - **上下文不是历史本身**：Tool Result prune 和 LLM Compaction 只改变下一次推理看到什么，不把已记录的证据当作上下文垃圾删除。 -- **任务可以长于一个 Turn**：Headless 使用 TaskRun、Task Event Log、预算和 continuation 机制推进可中断、可检查的长程任务。 -- **反馈不等于事实 authority**：Self-check 可以产生证据和一次受限修复机会，但不能把“我检查过了”变成系统事实。 +- **唯一执行 authority**：Runtime Host 拥有 Session、Turn、agent lifecycle、continuation、tools 和 events；Eval 只拥有实验语义与结果。 完整设计见 [Maka Backend Architecture](./ARCHITECTURE.zh-CN.md)。 @@ -29,7 +28,7 @@ Maka 不只回答问题。它可以在受控权限下阅读项目、执行工具 |---|---|---| | **Desktop** | 日常交互、文件与 Artifact 工作流、模型和权限配置 | Electron + React，支持流式会话、工具时间线、分支、搜索和恢复 | | **TUI / CLI** | 在当前工程目录中使用 Maka，或执行单次非交互 Turn | `maka`、`maka run`，复用 Desktop 的 workspace 和模型连接 | -| **Headless** | 长程任务、可恢复 TaskRun、实验和评估 | `maka eval`，支持任务日志、导出、恢复和对比 | +| **Eval** | Maka 与外部 subject 的可复现实验 | `maka eval run --out ` | ## 当前能力 @@ -47,12 +46,12 @@ Maka 不只回答问题。它可以在受控权限下阅读项目、执行工具 - 本地记忆、联网搜索和机器人入口； - 不同集成需要单独配置，并非所有实验入口默认可用。 -### Durable Tasks and Evolution +### Evaluation -- Append-only Task Event Log 与 TaskRun projection； -- 预算、权限暂停、continuation、结果导出和失败任务重试； -- 有计划、source-guarded、次数受限的 Heavy-task Self-check； -- AHE target protocol 与 evidence export；完整自动自迭代仍属于外部/实验流程。 +- 声明式多臂 Experiment 展开为 task × repetition × subject cell； +- 每个 cell 使用 immutable attempt，基础设施失败只替换该 cell，并选择最早有效 attempt； +- 通用结果只包含 score、normalized usage、可归因 cost、duration、status/failure reason 与 artifacts； +- Maka subject 只通过 Runtime Host 执行，外部竞品使用 generic external subject adapter。 ## 快速开始 @@ -128,7 +127,7 @@ TUI 同时支持 `/graph on`、`/graph off` 和 `/graph <任务>`。非交互 Graph 的 implementation operator 使用隔离的 Git worktree，因此源项目必须是干净的 Git worktree。 -CLI 读取 Desktop 写入的同一份模型连接和 workspace 配置。Headless 的完整命令与 trust posture 见 [`packages/headless/README.md`](./packages/headless/README.md)。 +CLI 读取 Desktop 写入的同一份模型连接和 workspace 配置。评测 spec 和 adapter 位于 [`packages/eval`](./packages/eval)。 ## 架构 @@ -141,7 +140,9 @@ Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun ↓ Context / Session / UI projections -Headless / Eval → Task Event Log → TaskRun → Self-check / AHE evidence +Experiment → Cells → Attempts → Results + ↓ + Runtime Host 执行 Maka subjects ``` 从 [ARCHITECTURE.zh-CN.md](./ARCHITECTURE.zh-CN.md) 开始阅读。它提供总体架构图、代码边界、按问题组织的阅读路径，以及六篇中英双语深度文章。 @@ -154,7 +155,7 @@ apps/desktop/ Electron main / preload / React renderer packages/core/ Session、Event、Permission、Connection 等纯 contracts packages/storage/ File-backed stores 与 run ledgers packages/runtime/ AgentRun、模型适配、工具、上下文和恢复 -packages/headless/ TaskRun、Autonomous Loop、Self-check、eval 与 AHE +packages/eval/ Experiment cell、attempt、result 与 executor/subject adapter packages/cli/ TUI 和非交互 CLI packages/ui/ 共享对话、Markdown、Artifact 与 UI primitives @@ -178,9 +179,9 @@ Maka 默认把 workspace 数据放在 Electron `userData` 下： - 会话和连接元数据保存在本地文件系统； - API key、bot token、proxy password 等运行凭据当前保存在本地 plaintext `credentials.json`，依赖 OS 账号边界，并在 POSIX 上强制目录 `0700`、文件 `0600`； -- 订阅 OAuth token（Claude、Codex、GitHub Copilot、xAI 以及 Antigravity preview）统一存放在同一份 `credentials.json`，它是 desktop、TUI、headless 的唯一凭据权威；历史 Electron `safeStorage` 凭据/token 文件不会被导入，仅保留这些历史副本的用户需要重新登录； +- 订阅 OAuth token（Claude、Codex、GitHub Copilot、xAI 以及 Antigravity preview）统一存放在同一份 `credentials.json`，它是 Runtime Host client 的唯一凭据权威；历史 Electron `safeStorage` 凭据/token 文件不会被导入，仅保留这些历史副本的用户需要重新登录； - Renderer 不接收明文凭据；文件写入、Shell 和危险工具调用需要经过 permission engine； -- Headless real-model eval 默认 fail closed，要求调用方显式提供外部隔离边界。 +- Eval 不构造 Runtime，也不读取 Runtime storage；Maka subject 连接已有 Runtime Host。 安全问题请阅读 [SECURITY.md](./SECURITY.md)，当前隐私和 sandbox contract 见 [docs/README.md](./docs/README.md)。 @@ -215,7 +216,7 @@ npm run check:release ```sh npm --workspace @maka/runtime test -npm --workspace @maka/headless test +npm --workspace @maka/eval test npm --workspace @maka/desktop test ``` diff --git a/SECURITY.md b/SECURITY.md index afa57db229..d9f5a2d565 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -94,7 +94,7 @@ supply their own boundary. See file mode 0o600, atomic writes, and no symlink/traversal escape. Subscription OAuth tokens (Claude, Codex, GitHub Copilot, xAI, and the Antigravity preview) live in the same store: `credentials.json` - is the single authority every surface — Desktop, TUI, headless — + is the single authority every Runtime Host surface — Desktop, TUI, CLI — reads and writes, under the same OS-account and 0o700/0o600 boundary as other runtime credentials. Electron safeStorage is not part of this boundary anymore. Pre-existing safeStorage-encrypted credential diff --git a/apps/desktop/tsconfig.storybook.json b/apps/desktop/tsconfig.storybook.json index 8d14d4269e..f087126829 100644 --- a/apps/desktop/tsconfig.storybook.json +++ b/apps/desktop/tsconfig.storybook.json @@ -13,7 +13,6 @@ "@maka/core": ["../../packages/core/src/index.ts"], "@maka/runtime": ["../../packages/runtime/src/index.ts"], "@maka/storage": ["../../packages/storage/src/index.ts"], - "@maka/headless": ["../../packages/headless/src/index.ts"] } }, "include": [ diff --git a/docs/README.md b/docs/README.md index fa0fda3b72..98b0ddb5f4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,23 +14,21 @@ This page is the authority map for Maka documentation. Code and contract tests r - [Backend architecture](../ARCHITECTURE.md) ([中文](../ARCHITECTURE.zh-CN.md)) - [Desktop architecture](../apps/desktop/README.md) - [Renderer architecture](../apps/desktop/src/renderer/README.md) -- [Headless usage and isolation](../packages/headless/README.md) +- [Evaluation kernel](../packages/eval/README.md) - [Runtime package](../packages/runtime/README.md) - [UI package architecture](../packages/ui/README.md) - [Security policy](../SECURITY.md) ## Current contracts -### Runtime and Headless +### Runtime and Eval - [Deep Research durable workspace](./deep-research-durable-workspace.md) - [Session task ledger lifecycle](./session-task-ledger-lifecycle.md) -- [Execution identity and evidence spine](./execution-evidence-spine.md) - [Runtime resume architecture](./architecture/runtime-resume-architecture.md) ([中文](./architecture/runtime-resume-architecture.zh-CN.md)) - [Runtime Host architecture](./architecture/runtime-host-architecture.md) ([中文](./architecture/runtime-host-architecture.zh-CN.md)) - [Runtime resume extraction ledger](./architecture/runtime-resume-extraction-ledger.zh-CN.md) - [Runtime resume Phase 3–4 implementation route](./architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md) -- [AHE target protocol and evidence export](./ahe-target-protocol.md) - [Skill catalog policy](./skill-catalog-policy.md) - [Agent Swarm](./agent-swarm.md) - [Agent Graph stream scheduling](./architecture/agent-graph-stream-scheduling-draft.md) ([中文](./architecture/agent-graph-stream-scheduling-draft.zh-CN.md)) diff --git a/docs/ahe-target-protocol.md b/docs/ahe-target-protocol.md deleted file mode 100644 index a1e73707d5..0000000000 --- a/docs/ahe-target-protocol.md +++ /dev/null @@ -1,147 +0,0 @@ -# Maka AHE Target Protocol - -Maka exposes an AHE-facing target contract so AHE can run the outer -self-iteration loop without becoming part of Maka's interactive runtime. -Maka remains the source of truth for runtime events, tool execution, -permissions, artifacts, and official evaluation feedback. - -The source-backed TypeScript contract lives in -`packages/headless/src/ahe-target-protocol.ts`. Consumers should use the -`@maka/headless/ahe-target-protocol` subpath after build. - -## Protocol Files - -AHE should treat these files as the initial file protocol for a Maka target -snapshot and candidate iteration: - -- `target-snapshot.json`: a `MakaAheTargetSnapshot` with - `protocolVersion: "maka.ahe-target.v2"`, the source label, content-addressed - snapshot id, SHA-256 source manifest, optional Git metadata, and the - component map from `MAKA_AHE_CURRENT_COMPONENTS`. -- `harness-results.json`: a `MakaAheHarnessResults` object containing per-task - `maka.ahe.run_result.v1` rows. Each current row names its `taskRunId` and - content-bound execution-lineage ref. `official_pass` and `official_fail` are - valid only when `scoreAuthority` is `official_verifier` or `official_scorer`. -- `trace-index.json`: a `MakaAheTraceIndex` that maps every task id to Maka - execution lineage, payload-safe Task Events and AgentRun inspections, - optional canonical Runtime Event sources, messages, transcripts, tool - results, and artifacts. -- `change-manifest.json`: a `MakaAheChangeManifest` describing the staged - patch, source-backed components changed, failure evidence, root cause, - targeted fix, predicted fixes, risk cases, validation dataset, and rollback - criteria. -- `change-evaluation.json`: a `MakaAheChangeEvaluation` comparing baseline and - candidate official cells, including transition labels, observed and missed - predictions, regressions, infra/excluded tasks, and self-check-only tasks. - -All refs are opaque file/blob/url refs. The protocol does not require AHE -Python, NexAU, E2B, ADB, tmux, or Rive code in Maka runtime. - -## Evidence Export - -After recording Headless task runs, export a source-backed evidence snapshot with: - -```sh -maka eval ahe export \ - --store /runs \ - --repo \ - --out \ - [--run-id ] \ - [--source-label