@kodax-ai/kodax 0.7.67 → 0.7.69

package/CHANGELOG.md

@@ -6,6 +6,208 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.7.69] - Unreleased
+
+> Scope note: this release delivers **FEATURE_267**, **FEATURE_268**, and
+> **FEATURE_269** as one bounded interoperability/runtime release: bidirectional
+> A2A 1.0, split hot-reloadable integration configuration, and one authoritative
+> shared Coder daemon with secure host bridges. It does not expose the daemon
+> remotely, migrate Partner from its private embedded Runtime, or publish
+> credentials/Host Tools outside their bound run.
+
+### Added
+
+- **Bidirectional A2A 1.0 interoperability (FEATURE_267).** Added the
+  `@kodax-ai/kodax/a2a` integration edge: allowlisted Agent Card discovery and
+  a JSON-RPC/SSE executor over the existing F258 plane, plus an authenticated,
+  caller-scoped, durable Runtime-backed KodaX Agent server with continuation,
+  cancellation, ordered replay/subscription, and restart reattachment.
+- **No-code A2A product path and Runtime binding.** Added declarative
+  `a2a add/list/test/call/remove`, automatic `external:<name>` registration for
+  built-in Runtime owners, and explicit `a2a expose` / loopback-only `a2a
+  serve`. The inbound server can publish the Runtime default or one validated
+  user Markdown Agent with pinned Agent/Skill/tool/workspace revisions,
+  structured `toolPolicy`, `~/.agents/skills` discovery, and exact Skill-script
+  execution through the fail-closed ASRT adapter.
+- **Split integration configuration and hot reload (FEATURE_268).** MCP, A2A,
+  and Extensions now use one user-level versioned file per domain, backed by
+  four canonical templates, explicit lossless migration, locked atomic writes,
+  last-known-good watchers with metadata fallback, whole-provider MCP draining,
+  entry-transactional Extension/outbound-A2A reconciliation, and explicit
+  restart-required handling for inbound execution/store authority changes.
+- **A2A network and publication boundaries.** Outbound fetches enforce origin,
+  DNS/private-address, TLS, redirect, credential, timeout, content-type, and
+  size policy. The built-in server listener is loopback-only; public hosts use
+  `handle()` behind TLS. A2A 0.3, gRPC, HTTP+JSON, push notifications, automatic
+  public Agent exposure, and remote Runtime configuration are not advertised.
+- **Authoritative shared Coder daemon (FEATURE_269).** Added atomic
+  `sessions.observe()` join/resync, durable operation identities and receipts,
+  stable same-session ordering, settings/grant CAS, transport-safe AskUser and
+  permission resolution, live run projection, structured restart outcomes, and
+  a truthful per-capability Coder compatibility matrix for CLI, Space, IDE, and
+  SDK clients.
+- **Shared-daemon SDK completion.** Server-side Coder/Partner admission now
+  covers every session and run path; late-join snapshots include transcript
+  revision, managed tasks, queued continuation metadata, and reverse
+  requirements. The SDK adds prompt connection lifecycle signals, typed event
+  parsing with per-event degradation, daemon-safe run DTOs,
+  `agentMode`/`autoModeEngine` settings CAS, durable operation/Host Tool outcome
+  queries, and daemon stop/rollback preflight.
+- **Secure host bridges and owner fencing.** Provider credentials are supplied
+  just in time through stable-client/run/provider-bound leases and never
+  persisted. A keychain-held stable client secret can reattach credential and
+  Host Tool handlers after Space reconnects; Host Tools remain immutable and
+  run-bound, with fsynced dispatch truth and explicit unknown outcomes rather
+  than blind replay. Daemon and inline Coder ownership share one revisioned
+  fence with sticky rollback, while Partner remains isolated.
+
+### Changed
+
+- **Tool-result delivery now optimizes end-to-end context use.** Tool handlers
+  collect complete results and one aggregate next-request capacity owner keeps
+  every result inline when the batch fits. Default Bash processing no longer
+  applies command-specific lossy filters; its former 512 KiB capture limit is
+  now only a memory-to-disk spool threshold. Capacity is solved against the
+  final input (`Pmax`), so the 3% uncertainty margin grows with the admitted
+  batch instead of being frozen at the smaller pre-batch request.
+- **History compaction is physical-capacity driven.** Default automatic
+  compaction waits until the final provider envelope (system prompt, actual
+  tools, messages/framing, output reserve, and safety margin) cannot fit.
+  Default microcompaction and destructive pre-summary/fallback pruning are off;
+  pressure uses semantic summary first and stops as soon as the next request
+  fits. Static early percentages remain explicit opt-ins, and manual
+  `/compact` remains an explicit force operation.
+- **Self-knowledge follows the v0.7.69 capability surface.** `kodax_manual`
+  now documents the three split integration files and migration/hot-reload
+  behavior, the `/a2a` SDK subpath, atomic shared-daemon observation, durable
+  controls, run-scoped credentials/Host Tools, and daemon/inline ownership.
+
+### Fixed
+
+- **Recoverable overflow and hidden output caps.** Overflow of the final
+  operational request budget saves the complete result and emits one explicit
+  incomplete marker. Long lines have exact continuation offsets, completed task
+  output is complete, and hidden caps were removed from grep, glob, code search,
+  and retrieval rendering.
+- **Cache token accounting and history preservation.** Cache tokens are charged
+  once. Empty, failed, or insufficient summaries now surface a typed capacity
+  error while retaining the canonical transcript and immutable Worker prompt.
+- **Tool-result completeness and retention edge cases.** No-usage accounting
+  includes the final system prompt, active schemas, and same-request recovery;
+  explicit limits use one-extra-item probes; delayed Bash drain remains
+  recoverable. Referenced result/image artifacts and fresh checkpoints are no
+  longer removed by age-only cleanup.
+- **Post-review capacity correctness.** Trusted artifact metadata cannot be
+  forged by raw tool text; failures carry the last legal transcript; observers
+  see admitted content; child evidence uses the routed model's physical budget;
+  bounded acquisition exposes continuation instead of silent loss; direct Bash
+  artifacts remain canonical without nested spill markers.
+- **Windows process-tree fallback.** A failed or timed-out `taskkill /t` now
+  triggers a native Toolhelp parent snapshot before direct escalation, with
+  CIM/WMIC retained only as fallback. Agent and LLM cleanup stay aligned and a
+  real nested-process regression proves descendants exit.
+- **Windows lock deletion races.** Proposal and lifecycle lock probes treat
+  transient `EPERM`/`EACCES`/`EBUSY` as non-stale and retry, preserving the
+  fail-closed owner-token contract during concurrent removal.
+- **Frozen FEATURE_259 eval inputs.** The pre-iteration dispatch schema is
+  reconstructed from its historical bytes, so later production tool-schema
+  improvements cannot mutate the baseline or invite a hash-only CI workaround.
+- **Governed-memory Bash guard bypasses.** Commands that directly address
+  recognized scoped or legacy memory roots now permit only one simple read-only
+  inspection; command chaining, pipelines, redirects, home-relative paths, and
+  interpreter writes fail closed at the Bash tool boundary.
+- **Memory proposal and review persistence integrity.** Invalid approval
+  metadata now produces a store warning and blocks rewrites; project-less review
+  drains no longer claim project-owned work; persisted outcome evidence receives
+  full shape validation; atomic writes clean temporary files on failure.
+- **Memory store lock ownership.** Proposal and lifecycle locks now carry a PID
+  plus random owner token, avoid reclaiming stale locks held by a live process,
+  and remove a lock only when the releasing owner token still matches. Lifecycle
+  state writes now use temporary-file rename instead of direct truncating writes.
+- **Interactive resume handoff and large-store startup.** Bare `kodax -r` now
+  keeps the selected session through the picker-to-TUI handoff instead of
+  exiting, and the picker uses bounded metadata paging instead of repeatedly
+  full-reading every matching session before it opens.
+- **A2A/configuration release hardening.** Review gaps in remote execution,
+  Skill-script admission/isolation, hot reload, listener preparation, binding
+  pinning, last-known-good reconciliation, and redacted diagnostics now fail
+  closed or retain the prior healthy revision as specified. The public A2A
+  server type now exposes its existing readiness wait, validated DNS results
+  narrow explicitly to IPv4/IPv6, and safe request-body typing no longer
+  depends on an undeclared DOM global, keeping root TypeScript validation green.
+
+## [0.7.68] - 2026-07-12
+
+> Scope note: this release delivers **FEATURE_260**, the KodaX Memory Agent,
+> as a thin experimental SDK and governed runtime extension over the existing
+> F228 Memory Control Plane. It does not add a second memory database, a
+> resident specialist agent, filesystem memory actions, or online self-modification.
+
+### Added
+
+- **Thin experimental Memory Agent SDK.** Added
+  `@kodax-ai/agent/experimental-memory` and the root `/experimental-memory`
+  entry with scoped `MemorySession` lifecycle, zero-wait passive recall,
+  read-only deliberate `query()`, bounded observations, and episode outcomes.
+- **Deliberate governed recall for the Action LLM.** A session-bound
+  `memory_recall` tool exposes only one `need` field, returns prompt-safe
+  low-authority evidence from the same F228 plane, and keeps identity, scope,
+  revision, and sequence outside model input.
+- **Auditable memory decisions and outcomes.** Trace-only
+  `MemoryDecisionReceipt` records candidate/selected/injected refs and policy
+  version; accepted Outcome Digests can conservatively link influence without
+  storing hidden reasoning or creating a second event store.
+- **Bounded episode review and promotion.** Timed-out review work persists in a
+  scoped inbox for bounded next-session drain and revalidation. Promotion now
+  consults compatible claims before choosing create, evidence update,
+  condition refinement, conflict, no-action, reject, or quarantine.
+
+### Changed
+
+- **Memory applicability is exact and fail-closed.** Tenant, user, agent,
+  workspace, project, and branch identity participate in deterministic scope
+  checks; sibling/cross-user/cross-tenant fallback is prohibited.
+- **Memory policy is source-versioned and cache-safe.** `f260-v0.7.68.2`
+  binds production reminder rules, evidence rendering, and deliberate-recall
+  tool bytes. Passive reminders only affect the dynamic suffix; deliberate
+  queries add a normal tool-call/result tail while preserving earlier provider
+  cache bytes.
+- **Safety-critical boundaries remain deterministic.** Secret filtering,
+  memory-file mutation guards, poisoning/source-evidence checks, and governed
+  proposal/preview/fingerprint/apply remain zero-violation code gates rather
+  than probabilistic LLM recall thresholds.
+- **Self-knowledge follows the v0.7.68 capability surface.** `kodax_manual`
+  now has a dedicated governed-memory topic, names all 43 built-in slash
+  commands under a two-way drift guard, and documents the current 10 SDK
+  subpaths plus Runtime and `/experimental-memory` ownership boundaries.
+
+### Fixed
+
+- **Post-review Memory Agent release hardening.** Repository identity now strips
+  Git remote userinfo/query credentials before scoped or legacy persistence;
+  managed-path guards are Windows-case-safe, protect governance sidecars, and
+  fail closed for non-read-only shell access to addressed memory roots. Episode
+  reviews use atomic processing claims with stale recovery, while proposal and
+  lifecycle stores serialize concurrent read-modify-write updates. Eval manifest
+  schema v2 binds untracked file bytes in addition to the tracked patch, corrupt
+  raw JSON fails loudly, and summary review state points to the separate
+  main-session review artifact instead of remaining permanently pending.
+- **Runtime daemon state replacement is atomic.** Daemon lifecycle updates now
+  stage and rename `daemon.json` instead of truncating it in place, preventing
+  shutdown polling from mistaking a partial write for completed cleanup and
+  leaving an orphaned `stopping` process under full-suite load.
+
+### Performance
+
+- **The preregistered v2 memory-routing panel passes all release gates.** On
+  `ark/v4flash`, general immediate recall passed 59/60 (98.3%), high-value
+  recall 40/40, must-silent 200/200 (Wilson lower 98.1%), paired routing lift
+  was +73.3 percentage points with zero control regression, and bounded
+  two-decision recovery passed 20/20. The 520-cell panel represented 782,721
+  tokens and an estimated $0.004447 against the $0.02 cap. Main-session blinded
+  review recommends ship for routing value while documenting that the panel is
+  not an end-to-end task-completion claim.
+
 ## [0.7.67] - 2026-07-11
 
 > Scope note: a stabilization and agent-efficiency release. **FEATURE_258**
@@ -321,7 +523,11 @@ All notable changes to this project will be documented in this file.
   stale wide-char or skipped-cell residue cannot remain after user-driven
   transcript scrolling.
 
-## [0.7.61] - 2026-07-06
+## [0.7.61] - 2026-07-06
+
+> Historical release record: the command-aware lossy-filter behavior below is
+> what v0.7.61 shipped, not the current default. The 2026-07-14 correction is
+> recorded under Unreleased, ADR-050, and the FEATURE_251 design/test guide.
 
 > Scope note: a token-efficiency + workflow-reliability release. **FEATURE_251** adds command-aware
 > in-tool output compression (an rtk-style Token Killer port) inside KodaX's own `bash` tool layer,
@@ -335,7 +541,7 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
-- **Tool-output semantic compression — command-aware in-tool Token Killer (FEATURE_251, ADR-050).** A new `packages/coding/src/tools/output-filters/` module compresses bash `stdout`/`stderr` **body** after decode, before the `Command:` / `Exit:` header is assembled, at the single `bash.ts` close-handler integration point (so both the SA and AMA dispatch paths are covered by one change). It ships a lossless generic layer (ANSI strip), compiled stateful filters (`git-diff`, `git-log`, `git-status`, `test-runner` failure-focus, `lint` diagnostic grouping, `json-output` / NDJSON structural summary), and a built-in declarative long-tail table (package-manager / docker / infra CLI progress). Hard constraints: the `Command:` / `Exit:` header is preserved verbatim (FEATURE_185 hits-ledger depends on it); the generic layer is lossless-by-construction with `never_worse` as a size-only backstop; content-signature detection is preferred over command-name matching (robust to compound commands and pipes); and every lossy filter (`lossiness: tail | whole`) first persists the raw decoded body via `persistToolOutput` and appends a recovery hint, falling back to the raw body + existing tail-truncation if the persist fails. `background` / `timeout` / `abort` paths do not reach the completion assembly and are naturally excluded. Isolated Layer-1 measurements (`context-savings.test.ts`) show ~66–99% body-token reduction on high-noise commands (e.g. a 120-file `git diff` 9,960 → 1,344 tokens; a `terraform apply` progress stream 10,617 → 59). Deterministic code — no prompt change, no FEATURE_104 eval. Human test guide: `docs/test-guides/FEATURE_251_v0.7.61_TEST_GUIDE.md`.
+- **Historical implementation — tool-output semantic compression / command-aware in-tool Token Killer (FEATURE_251, ADR-050).** A new `packages/coding/src/tools/output-filters/` module compressed bash `stdout`/`stderr` **body** after decode, before the `Command:` / `Exit:` header was assembled, at the single `bash.ts` close-handler integration point (so both the SA and AMA dispatch paths were covered by one change). It shipped a lossless generic layer (ANSI strip), compiled stateful filters (`git-diff`, `git-log`, `git-status`, `test-runner` failure-focus, `lint` diagnostic grouping, `json-output` / NDJSON structural summary), and a built-in declarative long-tail table (package-manager / docker / infra CLI progress). Hard constraints at release time: the `Command:` / `Exit:` header was preserved verbatim (FEATURE_185 hits-ledger depends on it); the generic layer was lossless-by-construction with `never_worse` as a size-only backstop; and every lossy filter persisted raw decoded body before appending a recovery hint. Isolated Layer-1 fixtures measured shorter bodies, but did not measure recovery reads, extra inference rounds, or task-level evidence quality; they are historical measurements, not current release gates or end-to-end benefit claims. Current default behavior is the correction described above. Human test guide: `docs/test-guides/FEATURE_251_v0.7.61_TEST_GUIDE.md`.
 - **Deterministic workflow-quality preflight lint (FEATURE_252).** A new `packages/agent/src/workflow/quality-lint.ts` (`lintRestrictedWorkflowSource` / `assertRestrictedWorkflowQuality`, exported from the workflow package) runs inside restricted workflow module materialization (`script-runner.ts` `createRestrictedWorkflowModule`) and in the coding workflow host with host-policy `maxAgents`, so structural contract violations fail before a run can start — matching the existing inline-smoke hard-fail feedback loop. It hard-fails three deterministic contract classes only: (1) an unawaited workflow-command variable (`wf.runAgent` / `wf.spawnAgent` / `wf.wait` / `wf.synthesize` / `wf.workflow` / `wf.artifact`) used in a boolean position (`if (x)`, `!x`, ternary test, `x && …`, `x || …`, loop test) — a case a runtime Proxy cannot catch because object truthiness has no Proxy trap; (2) top-level structured-output field access (`result.findings`, `result.summary`, …) when the fields belong under `result.structured`; and (3) a literal `[...]`/`[...].map(...)` agent fanout whose static upper bound exceeds `manifest.maxAgents` or a known host cap. Review/verifier/generic quality heuristics are intentionally **not** emitted as model-visible warnings (a lightweight AST pass cannot distinguish a weak workflow from a valid optimized one, and surfacing them causes needless rewrite churn). Human test guide: `docs/test-guides/FEATURE_252_v0.7.61_TEST_GUIDE.md`.
 
 ### Changed
@@ -2222,7 +2428,7 @@ repl            → coding, skills
 ### Tests
 - Added / expanded tests for `task-engine`, `reasoning`, `tool-display`, `live-streaming`, `StatusBar`, `invocation-runtime`, `types-legacy`, and `InkREPL.interrupted`
 
-<!-- last-sync: fe6ca81a -->
+<!-- last-sync: cf5f273b -->
 
 ### Added
 - **Repository intelligence substrate (FEATURE_018)**: Task-aware repository intelligence layer under `.agent/repo-intelligence/` with durable artifacts — `repo-overview.json`, `changed-scope.json`, `module-index.json`, `symbol-index.json`, `process-index.json`, `repo-intelligence-manifest.json` — supporting incremental refresh, freshness metadata, and language-tiered extraction (TS/JS via AST, Python, Go, Rust, Java, C++)

package/README.md

@@ -359,13 +359,26 @@ experiments.
 One daemon owns many sessions. Different sessions may run concurrently; starts
 within the same session are queued so that only one run is active for that
 session. Multiple `kodax` processes can attach to the same daemon and open or
-observe different sessions.
+observe the same session. FEATURE_269 adds atomic snapshot-plus-stream joining,
+durable idempotent mutations, revision-safe settings and grants, transport-safe
+AskUser/permission responses, run-scoped credential and Host Tool bridges, and
+one daemon/inline Coder owner fence. In-flight external effects are never
+blindly replayed after a crash; clients receive explicit interrupted/unknown
+terminal facts and resync when `runtimeId` changes.
+
+Space and IDE hosts should require these capabilities through the Runtime SDK.
+Partner remains on its private inline Runtime and must use a distinct product
+data/session root. A missing daemon capability is an error, not permission to
+silently fall back to inline Coder.
 
 For the full host-integration contract, including inline/Worker/daemon selection,
 multi-client permission handling, config/catalog/MCP admin APIs, artifacts,
 context diagnostics, and daemon protocol schemas, see
 [docs/SDK_EMBEDDER_GUIDE.md §17](docs/SDK_EMBEDDER_GUIDE.md#17-runtime-sdk-worker-isolation-and-local-daemon-feature_253-feature_257).
 
+The Space/IDE shared-daemon contract is documented in
+[SDK Embedder Guide section 23](docs/SDK_EMBEDDER_GUIDE.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769).
+
 ## Repo Intelligence
 
 KodaX ships with built-in repo intelligence (`repo_overview`, `module_context`, `symbol_context`, `process_context`, `impact_estimate`, and related tools) that helps the coding agent understand large codebases without ad-hoc grep/glob exploration.
@@ -379,7 +392,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## Architecture
 
-KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 9 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
+KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 11 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`, `/a2a`, `/experimental-memory`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
 
 ```
 KodaX/
@@ -405,7 +418,7 @@ KodaX/
 │
 ├── src/                     # CLI entry + SDK subpath entries
 │   ├── kodax_cli.ts         # Main CLI entry point (bin: `kodax`)
-│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime}
+│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,a2a,experimental-memory}
 │
 └── package.json             # Root workspace config; release.mjs rewrites name + injects subpath exports
 ```
@@ -454,9 +467,9 @@ Source-side workspace package names (`@kodax-ai/*`). npm consumers install the s
 KodaX has two layers that consumers should understand separately:
 
 - **Source-side**: 4 workspace packages above (what developers see when reading the repo).
-- **npm-published**: a single bundled package `@kodax-ai/kodax` with 9 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
+- **npm-published**: a single bundled package `@kodax-ai/kodax` with 11 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
   - **Full-package subpaths** (`/agent`, `/llm`, `/coding`, `/repl`) — each one maps 1:1 to a source workspace and exposes its complete public API.
-  - **Narrow-subset subpaths** (`/media`, `/skills`, `/mcp`, `/session`) — each one exposes only a focused capability slice carved out of `/agent` or `/repl`. This lets consumers who only need (say) the Skills system import a much smaller surface without pulling in the full agent framework.
+  - **Integration and narrow subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/runtime`, `/a2a`, `/experimental-memory`) — focused host surfaces. `/a2a` composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to `/agent`.
 
 | Source package | npm subpath | Type | What you get | Example consumer |
 |---|---|---|---|---|
@@ -465,10 +478,12 @@ KodaX has two layers that consumers should understand separately:
 | `packages/agent`  | `@kodax-ai/kodax/skills`  | **Narrow subset** | Skills system only — `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` / ... (26 exports = pre-v0.7.43 `@kodax-ai/skills` complete API) | Skill loaders, IDE plugins |
 | `packages/agent`  | `@kodax-ai/kodax/mcp`     | **Narrow subset** | MCP only — `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` / ... (23 exports) | MCP server hosts |
 | `packages/agent`  | `@kodax-ai/kodax/media`   | **Narrow subset** | Structured image/file/video input-artifact helpers (22 exports) | Desktop hosts and multimodal clients |
+| `packages/agent`  | `@kodax-ai/kodax/experimental-memory` | **Experimental subset** | Thin F228-backed `MemoryAgent` / `MemorySession` contracts for scoped recall, deliberate query, observations, and outcomes | SDK hosts explicitly evaluating FEATURE_260 |
 | `packages/coding` | `@kodax-ai/kodax/coding`  | Full package | Coding agent + 50+ tools + repo-intelligence (505 exports) | Build a Claude Code-shape product |
 | `packages/repl`   | `@kodax-ai/kodax/repl`    | Full package | Ink TUI + permission modes + commands (217 exports) | Terminal-UI consumers |
 | `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... (17 exports) | IDE plugins and desktop hosts reading session history |
 | `src`             | `@kodax-ai/kodax/runtime` | Host API | Embedded/Worker/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports) | SDK hosts, Space/IDE clients, daemon clients |
+| `src`             | `@kodax-ai/kodax/a2a` | Integration edge | A2A 1.0 Agent Card discovery, JSON-RPC/SSE F258 executor, safe fetch policy, and authenticated Runtime-backed Agent server | Agent orchestrators and KodaX hosts |
 
 **Rule of thumb**: if you need Runner / Agent / fan-out, import from `/agent`. If you only need skills or mcp APIs, import from `/skills` or `/mcp` to get a smaller bundle. The narrow subsets are subsets of the full packages — they do **not** expose extra symbols.
 
@@ -484,7 +499,7 @@ KodaX has two layers that consumers should understand separately:
 
 **Progressive Disclosure on the Managed Tool Path (FEATURE_250, v0.7.60)**: the deferred-tool progressive-disclosure mechanism — previously SA-path-only — now applies to the AMA/AMAW **managed** path too. Cache-cold managed turns carry one-line search hints instead of full descriptions for the 13 non-mcp deferred tools (repo-intelligence + web/code + goal); each tool's `input_schema` is unchanged, so it stays directly callable and the full description is fetched on demand via `tool_search`. `mcp_*` stay resident and `run_workflow` is untouched. Transparent to users; validated by two 5-alias eval panels (DEFER_SAFE 5/5, 0% read/grep fallback). See [docs/features/v0.7.60.md](docs/features/v0.7.60.md).
 
-**Tool-Output Compression + Workflow Quality Preflight (FEATURE_251 + FEATURE_252, v0.7.61)**: KodaX's own `bash` tool now compresses noisy command output **inside the tool**, so a big `git diff`, test run, package install, or `docker build` no longer spends thousands of context tokens — command-aware filters (git/test/lint/JSON + a declarative package/docker/infra long-tail) summarize the stdout/stderr body while the `Command:`/`Exit:` header stays verbatim and every lossy summary keeps a raw-recovery path; isolated measurements show ~66–99% body-token reduction. Alongside it, inline `run_workflow` gains a deterministic pre-start quality lint that hard-fails weak-model authoring contract bugs (unawaited workflow-command used as a boolean, top-level access of `result.structured` fields, literal agent fanout above manifest/host caps) before a run starts. Both are deterministic (no prompt change). See [docs/features/v0.7.61.md](docs/features/v0.7.61.md) and [docs/ADR.md ADR-050](docs/ADR.md).
+**Context-Efficient Tool Results + Workflow Quality Preflight (FEATURE_251 + FEATURE_252, v0.7.61; corrected 2026-07-14)**: local tools collect complete output and apply only contract-equivalent normalization that is strictly shorter; command-specific lossy Bash filters are off by default, and compound Bash uses no semantic adapter. One owner evaluates the complete parallel-result batch against the final provider request: it solves the largest final input `Pmax` for which `Pmax + output reserve + max(2048, 3% of Pmax) <= context window`, then admits only the remaining physical capacity. Results stay verbatim whenever they fit; only real overflow persists the complete value and emits `KODAX_RESULT_INCOMPLETE`. History follows the same physical-capacity rule: no default lossy microcompaction below capacity, summary-first at actual pressure, and typed failure without silent message deletion when a recoverable request cannot be formed. Static early percentages are explicit opt-ins. FEATURE_252's deterministic pre-start workflow contract lint is unchanged. See [docs/features/v0.7.61.md](docs/features/v0.7.61.md) and [docs/ADR.md ADR-050](docs/ADR.md).
 
 **External Agent SDK Plane (FEATURE_258, v0.7.67)**: `/agent` exports the protocol-neutral executor, registration, policy, credential-broker, artifact-policy, catalog, and durable task contracts. `/runtime` exposes the installed plane through `admin.agentRegistrations`, `agents`, and `agentTasks`, with the same DTO service methods over embedded and daemon clients. Executor factories are host functions: install them in an inline owner or while creating a new in-process daemon owner; they cannot be injected through an existing daemon connection or across a Runtime Worker boundary. Plane shutdown is terminal: pending waits and all later service calls reject. Restricted Workflow scripts preserve validated `phase` and external `target` routing. See the [complete owner/consumer recipes and safety contract](docs/SDK_EMBEDDER_GUIDE.md#18-external-agent-executor-plane-feature_258-v0767).
 
@@ -492,6 +507,39 @@ KodaX has two layers that consumers should understand separately:
 
 **Paged Session Listing (FEATURE_261, v0.7.67)**: both `/session` `listSessions()` and `runtime.sessions.list()` accept an exact `surface` filter and opaque continuation `cursor`; each returned summary carries the cursor for the next page. Filtering happens before the page limit, so a host does not need to over-fetch mixed surfaces. See the [pagination recipes](docs/SDK_EMBEDDER_GUIDE.md#19-session-surface-filtering-and-cursor-pagination-feature_261-v0767).
 
+**Experimental Memory Agent SDK (FEATURE_260, v0.7.68)**: `/experimental-memory` exposes the thin agent-layer `MemoryAgent` and scoped `MemorySession` lifecycle over the existing governed F228 plane. Passive recall is zero-wait; `query()` is read-only and deliberate; durable changes still require the proposal/preview/fingerprint/apply path. The Action LLM remains the final decision maker, recalled content stays low-authority, and safety/scope gates remain deterministic. See the [direct session and boundary guide](docs/SDK_EMBEDDER_GUIDE.md#21-experimental-governed-memory--experimental-memory-feature_260-v0768).
+
+**Bidirectional A2A 1.0 (FEATURE_267, v0.7.69)**: `/a2a` discovers allowed Agent Cards and installs a JSON-RPC/SSE executor through the existing F258 plane. Configured outbound Agents are also registered automatically as `external:<name>` in embedded CLI and user-daemon Runtimes, so the main Agent can orchestrate them without host code. The same module can publish the Runtime default or one validated `~/.kodax/agents/*.md` Agent behind an authenticated Runtime facade. The built-in listener is loopback-only; public deployment uses `handle()` behind host-owned TLS and authorization. A2A 0.3, gRPC, HTTP+JSON, push notifications, and automatic public exposure are not advertised. See the [client/server recipes and security boundaries](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769).
+
+The complete built-in path is available without writing TypeScript:
+
+```bash
+# Call another A2A Agent
+kodax a2a add research https://agent.example/.well-known/agent-card.json --effect read
+kodax a2a test research
+kodax a2a call research "Summarize this topic"
+
+# Expose the Runtime default Agent, or pass a name from ~/.kodax/agents/*.md
+export KODAX_A2A_TOKEN='replace-with-a-long-random-token'
+kodax a2a expose                 # or: kodax a2a expose document-agent
+kodax a2a serve                  # loopback http://127.0.0.1:8765
+```
+
+MCP, A2A, and Extension declarations live in one user file per domain under
+`~/.kodax/integrations/`. Use `kodax config template <mcp|a2a|extensions>`,
+`kodax integrations migrate --apply`, and the `kodax mcp`, `kodax a2a`, or
+`kodax extensions` commands to manage them. Running CLI/daemon hosts retain the
+last valid revision, atomically replace the complete MCP provider, reconcile
+Extensions per entry, and hot-register outbound A2A Agents. `a2a serve` loads
+its configured MCP/Extension capability surface before listening and pins that
+execution authority; it hot-reloads publication, authentication, and limits.
+Agent, Skill, Extension-tool authority, workspace, tool-policy, or task-store
+changes require an explicit server restart. Managed
+A2A contexts default to `~/kodax_a2a_server_workspace/<profile>/contexts/`.
+Exact Skill scripts require the opt-in isolated policy and a passing
+`kodax sandbox doctor` (`kodax sandbox setup` performs the explicit Windows
+one-time provisioning).
+
 ---
 
 ## Features
@@ -607,9 +655,10 @@ import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL config /
 import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager (v0.7.42)
 import { listSessions } from '@kodax-ai/kodax/session';         // session history helpers
 import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/daemon runtime API
+import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 client/server edge
 ```
 
-All 10 SDK entries (root + 9 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+All 12 SDK entries (root + 11 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
 
 For the complete host-facing contract — including embedded/Worker/daemon ownership,
 external-agent registration and task control, session cursor pagination, workflow
@@ -912,7 +961,7 @@ await runKodaX({
 
 ## SDK Usage
 
-KodaX ships as a single npm package `@kodax-ai/kodax` with 9 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime`). Each subpath is tree-shake-friendly so consumers pull only what they need:
+KodaX ships as a single npm package `@kodax-ai/kodax` with 11 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime` + v0.7.68 `/experimental-memory` + v0.7.69 `/a2a`). Each subpath is tree-shake-friendly so consumers pull only what they need:
 
 ```bash
 npm install @kodax-ai/kodax
@@ -929,6 +978,8 @@ import { SkillRegistry } from '@kodax-ai/kodax/skills';           // zero-dep sk
 import { createMcpManager } from '@kodax-ai/kodax/mcp';           // MCP popout manager (v0.7.42)
 import { listSessions } from '@kodax-ai/kodax/session';           // session history helpers
 import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';     // embedded/daemon runtime API
+import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';      // A2A 1.0 client/server edge
+import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in experimental memory SDK
 ```
 
 > The SDK is **ESM-only**. CommonJS consumers (Electron main / Webpack CJS / `require()` callers) must use `await import('@kodax-ai/kodax/...')` — see [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles).
@@ -1078,6 +1129,7 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 | Coding tasks | `@kodax-ai/kodax/coding` | Complete coding agent + tools |
 | Terminal app | `@kodax-ai/kodax/repl` | Full interactive experience |
 | Runtime host / daemon client | `@kodax-ai/kodax/runtime` | Sessions, runs, events, permissions, catalog, MCP, artifacts, diagnostics |
+| Experimental governed memory | `@kodax-ai/kodax/experimental-memory` | Scoped `MemoryAgent` / `MemorySession` recall and outcome contracts |
 
 ---
 
@@ -1143,7 +1195,7 @@ KodaX ships 50+ built-in tools, grouped below. They are registered as a single f
 ### Shell & search
 | Tool | Description |
 |------|-------------|
-| `bash` | Execute a shell command (supports `run_in_background`, output truncation) |
+| `bash` | Execute a shell command (supports `run_in_background`; complete capture with recoverable capacity fallback) |
 | `glob` | Find files by pattern |
 | `grep` | Regex content search (context lines, multiline, file-type filter, pagination) |
 | `code_search` | Lower-noise code search (extension-provider aware) |

package/README_CN.md

@@ -66,6 +66,21 @@ kodax
 
 ---
 
+## Runtime SDK 与共享 daemon
+
+`@kodax-ai/kodax/runtime` 支持 inline、Worker 和本机共享 daemon。FEATURE_269
+让 CLI、Space、IDE 与其他本地 SDK 客户端可以原子加入同一个 Coder
+session/run，共享 transcript、Todo、tool、AskUser、permission、队列与唯一终态。
+daemon mutation 使用持久 operation identity 和 revision CAS；崩溃后不会盲目重放
+可能已有副作用的 provider、run 或 Host Tool 调用。
+
+Space 的 provider credential 仍由 OS keychain 持有，只通过 run/provider-scoped
+broker 使用；Space Artifact/Office/Control 只通过显式绑定到该 run 的 Host Tool
+lease 暴露。CLI run 不会因为 Space 后来加入而继承这些能力。Partner 继续使用独立
+data/session root 下的 inline Runtime，不参与 Coder owner fence。capability 缺失时必须
+fail closed，不能静默退回 inline Coder。完整接入说明见
+[SDK Embedder Guide §23](docs/SDK_EMBEDDER_GUIDE.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769)。
+
 ## 为什么用 KodaX
 
 <table>
@@ -214,9 +229,11 @@ import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL 配置 /
 import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager（v0.7.42 起）
 import { listSessions } from '@kodax-ai/kodax/session';         // session 历史工具
 import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/Worker/daemon 宿主 API
+import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 双向接入
+import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in 实验性记忆 SDK
 ```
 
-10 个 SDK 入口（root + 9 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+12 个 SDK 入口（root + 11 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
 
 完整的宿主集成契约——包括 embedded/Worker/daemon 所有权、外部 Agent 注册与任务控制、session cursor 分页、workflow 模型分层和效率遥测——见 [SDK Embedder Integration Guide](docs/SDK_EMBEDDER_GUIDE.md)。
 
@@ -529,7 +546,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## 仓库结构
 
-KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 8 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`；ADR-024 + ADR-032 + ADR-038）。核心包：
+KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 11 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`、`/runtime`、`/a2a`、`/experimental-memory`；ADR-024 + ADR-032 + ADR-038）。核心包：
 
 | Workspace 包 | 作用 | 主要依赖 |
 |----|------|---------|
@@ -538,16 +555,16 @@ KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 works
 | `@kodax-ai/coding` | Coding Agent:50+ 工具(含 `dispatch_child_task`/`send_message`/`task_stop`)、role prompts、agent loop、auto-continue + repo-intelligence protocol(v0.7.43 inline) | `@kodax-ai/llm`, `@kodax-ai/agent` |
 | `@kodax-ai/repl` | 完整交互式终端 UI（Ink / React、权限模式、命令系统、流式渲染） | `@kodax-ai/coding`, `ink`, `react` |
 
-根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
+根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session,runtime,a2a,experimental-memory}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
 
 ### 源码层 vs npm 发布层
 
 KodaX 有两层结构，SDK 用户需要分开理解：
 
 - **源码层**：上面 4 个 workspace 包（开发者读代码时看到的物理结构）。
-- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 8 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
+- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 11 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
   - **完整包 subpath**（`/agent`、`/llm`、`/coding`、`/repl`）—— 每个 1:1 对应一个源码包，暴露完整公开 API。
-  - **窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`）—— 从 `/agent` 或 `/repl` 切出聚焦的能力子集，让"只用 Skills/MCP/会话管理"的消费者引入更小的依赖。
+  - **窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`、`/experimental-memory`）—— 从 `/agent` 或 `/repl` 切出聚焦能力；`/experimental-memory` 明确为 opt-in 不稳定接口。
 
 | 源码包 | npm subpath | 类型 | 内容 | 典型消费者 |
 |---|---|---|---|---|
@@ -556,10 +573,12 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 | `packages/agent`  | `@kodax-ai/kodax/skills`  | **窄子集** | 仅 Skills 系统 —— `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` 等 (26 exports = v0.7.43 之前 `@kodax-ai/skills` 完整 API) | Skill 加载器、IDE 插件 |
 | `packages/agent`  | `@kodax-ai/kodax/mcp`     | **窄子集** | 仅 MCP —— `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` 等 (23 exports) | MCP server 宿主 |
 | `packages/agent`  | `@kodax-ai/kodax/media`   | **窄子集** | 结构化图片/文件/视频输入 artifact helpers (22 exports) | 桌面宿主、多模态客户端 |
+| `packages/agent`  | `@kodax-ai/kodax/experimental-memory` | **实验性子集** | F228-backed `MemoryAgent` / `MemorySession` scope、recall、query、observation、outcome 契约 | 显式评估 FEATURE_260 的 SDK 宿主 |
 | `packages/coding` | `@kodax-ai/kodax/coding`  | 完整包 | Coding agent + 50+ 工具 + repo-intelligence (505 exports) | 构建 Claude Code 形态产品 |
 | `packages/repl`   | `@kodax-ai/kodax/repl`    | 完整包 | Ink TUI + 权限模式 + 命令系统 (217 exports) | 终端 UI 消费者 |
 | `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` 等 (17 exports) | 读取 session 历史的 IDE 插件和桌面宿主 |
 | `src`             | `@kodax-ai/kodax/runtime` | 宿主 API | Embedded/Worker/daemon facade，含 sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/外部 Agent 和 daemon schema (10 exports) | SDK 宿主、Space/IDE、daemon client |
+| `src`             | `@kodax-ai/kodax/a2a` | 集成边界 | A2A 1.0 Agent Card 发现、JSON-RPC/SSE F258 executor、安全 fetch 与鉴权 Runtime Agent server | Agent 编排器和 KodaX 宿主 |
 
 **经验法则**：需要 Runner / Agent / fan-out 时从 `/agent` 引入；只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入，bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
 
@@ -569,6 +588,36 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 
 **会话恢复与 ACP 污染修复（FEATURE_261，v0.7.67）**：直接运行 `kodax -r` 会进入可搜索、上下选择、Tab 补全和翻页的交互式会话选择器，并显示当前选中项的完整 session ID；`kodax -r <值>` 优先按完整 ID 恢复，ID 不存在时再按忽略大小写的完整标题匹配。标题唯一则直接恢复，同名标题则进入只包含候选项的选择器，绝不静默选第一条。`listSessions()` / Runtime / daemon 会话列表新增 `surface` 精确过滤和不透明 `cursor` 分页。ACP session 改为收到首个有效 prompt 后才持久化，ACP 测试强制使用临时 runtime home，避免测试记录写入真实 `~/.kodax/sessions`。`kodax -s cleanup-acp` 只预览严格匹配的空 ACP 污染记录；仅显式追加 `--apply-session-cleanup` 时才归档，不做永久删除。
 
+**实验性 Memory Agent SDK（FEATURE_260，v0.7.68）**：`/experimental-memory` 暴露基于既有 F228 治理平面的薄 `MemoryAgent` 与 scoped `MemorySession`。被动 recall 零等待，`query()` 只读且由主 Action LLM 主动选择；持久化仍必须经过 proposal/preview/fingerprint/apply。召回内容保持低权限，安全与 scope 边界仍由确定性代码门禁承担。直接 session 示例与宿主边界见 [SDK Embedder Guide §21](docs/SDK_EMBEDDER_GUIDE.md#21-experimental-governed-memory--experimental-memory-feature_260-v0768)。
+
+**双向 A2A 1.0（FEATURE_267，v0.7.69）**：`/a2a` 可发现 allowlist 内的 Agent Card，并通过既有 F258 plane 安装 JSON-RPC/SSE executor。配置中的出站 Agent 还会作为 `external:<name>` 自动注册到 embedded CLI 与用户 daemon Runtime，因此主 Agent 无需宿主代码即可编排。入站方向可以发布 Runtime 默认 Agent，或发布一个经过验证的 `~/.kodax/agents/*.md` Agent。内置 listener 仅允许 loopback；公网部署必须由宿主用 TLS、鉴权和授权包住 `handle()`。不宣称支持 A2A 0.3、gRPC、HTTP+JSON、push notification，也不会自动把本地 Agent 暴露到网络。详见 [SDK Embedder Guide §22](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769)。
+
+完整的内置调用路径不需要再写 TypeScript：
+
+```bash
+# 调用外部 A2A Agent
+kodax a2a add research https://agent.example/.well-known/agent-card.json --effect read
+kodax a2a test research
+kodax a2a call research "总结这个主题"
+
+# 暴露 Runtime 默认 Agent，或指定 ~/.kodax/agents/*.md 中的 Agent 名称
+export KODAX_A2A_TOKEN='请替换为足够长的随机令牌'
+kodax a2a expose                 # 或：kodax a2a expose document-agent
+kodax a2a serve                  # 仅监听 http://127.0.0.1:8765
+```
+
+MCP、A2A、Extension 分别使用 `~/.kodax/integrations/` 下的一个用户级文件。
+可以通过 `kodax config template <mcp|a2a|extensions>` 查看模板，通过
+`kodax integrations migrate --apply` 迁移旧配置，并用 `kodax mcp`、
+`kodax a2a`、`kodax extensions` 管理。运行中的 CLI/daemon 保留最后一个
+有效版本，完整替换 MCP provider、逐条协调 Extension，并热注册出站 A2A Agent。
+`a2a serve` 会在监听前装载已配置的 MCP/Extension 能力并固定执行权威，同时热加载
+公开信息、鉴权和限额。Agent、Skill、Extension 工具权威、工作区、tool policy
+或任务存储变更必须显式重启服务。
+托管 A2A 上下文默认位于 `~/kodax_a2a_server_workspace/<profile>/contexts/`。
+精确授权的 Skill 脚本必须使用隔离策略，并通过 `kodax sandbox doctor`；
+Windows 的一次性显式初始化由 `kodax sandbox setup` 完成。
+
 **外部 Agent SDK plane（FEATURE_258，v0.7.67）**：`/agent` 导出协议中立的 executor、registration、policy、credential broker、artifact policy、catalog 和 durable task 契约；`/runtime` 通过 `admin.agentRegistrations`、`agents`、`agentTasks` 向 embedded 与 daemon client 提供同一组 DTO API。Executor factory 是宿主函数，只能装入 inline owner，或在创建新的 in-process daemon owner 时装入；不能通过既有 daemon 连接或 Runtime Worker 边界注入。Plane 关闭后是终态：未完成的 wait 和后续所有服务调用都会拒绝；受限 Workflow 脚本会完整校验并传递 `phase` 与外部 `target`。完整所有权、注册、preflight、启动/等待/继续/取消/对账和安全边界见 [SDK Embedder Guide §18](docs/SDK_EMBEDDER_GUIDE.md#18-external-agent-executor-plane-feature_258-v0767)。
 
 **成本受控 Workflow SDK（FEATURE_259，v0.7.67）**：SDK 调用方用 run-scoped `modelTiers` 与 `workflow.maxConcurrency` 配置路由和并发，workflow 作者只表达 `fast` / `balanced` / `deep` 语义意图。terminal workflow event 回显 tier/source/fallback/usage/duration，持久化 `run.json.efficiencyReport` 给出 token coverage、role/tier 启动数、packet-read 拓扑、review wave 和 quality gate 结果。完整配置与遥测读取方式见 [SDK Embedder Guide §20](docs/SDK_EMBEDDER_GUIDE.md#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767)。
@@ -579,7 +628,7 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 
 **managed 工具路径的渐进披露（FEATURE_250，v0.7.60）**：deferred-tool 渐进披露机制——此前仅 SA path 拥有——现在也应用于 AMA/AMAW 的 **managed** path。缓存冷启的 managed 轮次对 13 个 non-mcp 延迟工具（repo-intelligence + web/code + goal）携带一行 search hint 而非完整描述；每个工具的 `input_schema` 不变，因此仍可直接调用，完整描述按需通过 `tool_search` 拉取。`mcp_*` 保持常驻，`run_workflow` 不动。对用户透明；由两个 5-alias eval panel 验证（DEFER_SAFE 5/5，0% read/grep 回退）。详见 [docs/features/v0.7.60.md](docs/features/v0.7.60.md)。
 
-**工具输出压缩 + Workflow 质量预检（FEATURE_251 + FEATURE_252，v0.7.61）**：KodaX 自有的 `bash` 工具现在**在工具内**压缩高噪声命令输出，一次大 `git diff`、测试、包安装或 `docker build` 不再吞掉数千 context token——命令感知过滤器（git/test/lint/JSON + 声明式 package/docker/infra 长尾）摘要 stdout/stderr 正文，`Command:`/`Exit:` 头部逐字保留，所有有损摘要都保留 raw 恢复路径；隔离测量显示正文 token 降幅约 66–99%。同时，inline `run_workflow` 新增确定性启动前质量 lint，在运行前硬失败弱模型的编写合约 bug（未 await 的 workflow-command 用作布尔、顶层访问本应位于 `result.structured` 的字段、字面 agent fanout 超 manifest/host 上限）。二者均为确定性（无 prompt 改动）。详见 [docs/features/v0.7.61.md](docs/features/v0.7.61.md) 与 [docs/ADR.md ADR-050](docs/ADR.md)。
+**上下文高效的工具结果 + Workflow 质量预检（FEATURE_251 + FEATURE_252，v0.7.61；2026-07-14 纠偏）**：本地工具先完整采集，只采用契约等价且严格更短的无损规范化；命令专用 Bash 有损过滤默认关闭，compound Bash 不使用语义 adapter。并行结果由唯一 owner 按最终 provider 请求统一判容：先求满足 `Pmax + 输出预留 + max(2048, Pmax 的 3%) <= 上下文窗口` 的最大最终输入，再只使用剩余物理容量。能放下就逐字交付，只有真实溢出才持久化完整结果并返回 `KODAX_RESULT_INCOMPLETE`。历史压缩使用同一物理容量规则：容量内不做默认有损 microcompaction，真实压力下 summary-first，无法形成可恢复请求时 typed failure，禁止静默删消息；静态提前百分比仅为显式 opt-in。FEATURE_252 的确定性 workflow 启动前合约 lint 保持不变。详见 [docs/features/v0.7.61.md](docs/features/v0.7.61.md) 与 [docs/ADR.md ADR-050](docs/ADR.md)。
 
 ```
 KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
@@ -596,9 +645,9 @@ KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 │   └── repl/                # @kodax-ai/repl —— Ink TUI
 ├── src/
 │   ├── kodax_cli.ts         # CLI 主入口（bin: `kodax`）
-│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime}
+│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,a2a,experimental-memory}
 ├── scripts/
-│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 9 SDK subpath + chunks）
+│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 11 SDK subpath + chunks）
 │   ├── build-binary.mjs     # Bun --compile 单文件二进制打包
 │   └── release.mjs          # ADR-024 release-time pkg name/exports 注入
 └── .github/workflows/
@@ -692,7 +741,7 @@ KodaX 现在会把 Repo Intelligence 的本地缓存分成内置引擎 profile
 ## 文档
 
 - [README.md](README.md) - 英文版 README
-- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成与 v0.7.67 公共 API 契约
+- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成与 v0.7.69 公共 API 契约
 - [docs/release.md](docs/release.md) - 单文件二进制构建与发布流程
 - [docs/PRD.md](docs/PRD.md) - 产品需求
 - [docs/ADR.md](docs/ADR.md) - 架构决策

package/config-templates/config.example.jsonc

@@ -0,0 +1,26 @@
+// KodaX core configuration template.
+// Copy only the fields you need to ~/.kodax/config.json (strict JSON).
+// MCP, A2A, and Extensions live in ~/.kodax/integrations/*.json; use
+// `kodax integrations migrate --dry-run` for legacy declarations.
+{
+  // "provider": "deepseek",
+  // "model": "deepseek-v4",
+  // "runtimeMode": "embedded",
+  // "effort": "high",
+  // "agentMode": "ama",
+  // "permissionMode": "accept-edits",
+  // "locale": "zh",
+  // "customProviders": [
+  //   {
+  //     "name": "my-relay",
+  //     "protocol": "openai",
+  //     "baseUrl": "https://api.example.com/v1",
+  //     "apiKeyEnv": "MY_RELAY_API_KEY",
+  //     "model": "provider/model",
+  //     "reasoning": { "efforts": ["off", "low", "high"], "default": "high" }
+  //   }
+  // ],
+  // "repoIntelligenceMode": "auto",
+  // "sessionRetentionDays": 0,
+  // "workflow": { "maxConcurrency": 8 }
+}