From add6a7d32ca84eb369ebc13d6965ea1223057871 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:42:07 +0800 Subject: [PATCH] docs(agent): record implemented contracts and precise VM/runtime completion gates --- doc/design/native-agent-flow-v3.md | 91 ++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 doc/design/native-agent-flow-v3.md diff --git a/doc/design/native-agent-flow-v3.md b/doc/design/native-agent-flow-v3.md new file mode 100644 index 0000000..d4b37c3 --- /dev/null +++ b/doc/design/native-agent-flow-v3.md @@ -0,0 +1,91 @@ +# Marqdo native agent flow — implementation contract + +Status: **incremental, draft**. This document distinguishes implemented interfaces from +the required interpreter/runtime changes. Do not claim stack-level suspension or +exactly-once external writes based on a checkpoint file. + +## Author surface (implemented in this branch) + +| Module | Function | Contract | +|---|---|---| +| ext/ai/context.mq.md | scope | Select a bounded source excerpt using parsed Markdown headings; ambiguous names fail closed | +| ext/ai/context.mq.md | pack | Compact caller-provided file/class/function text via ContextPackV2 | +| ext/ai/flow.mq.md | ask/choose/parse_choice | One short decision, allowed-choice verification, at most one format repair | +| ext/ai/flow.mq.md | input/reply | Durable step-boundary user-input gate keyed by id + source revision and scope | +| ext/ai/flow.mq.md | start/wait/parallel | Existing Marqdo subtask scheduler, failure-preserving parallel result aggregation | +| ext/ai/flow.mq.md | enter | Resolve only author-supplied registered skill name, run via standard subtask path | +| ext/ai/recovery.mq.md | decide/save/load | Native error policy and CheckpointV2; no implicit unsafe re-execution | + +The native agent plugin provides `agent_choice_parse`, `agent_context_scope`, +`agent_input_open`, `agent_input_resume` and `agent_parallel_report`. +Plugin errors must be visible, never converted into a fabricated successful answer. + +## Invariants + +- A model choice is untrusted data until verified against an explicit option list. +- An imported module is **not** automatically part of a model prompt. +- The requested heading scope, not the entire source file, is the prompt source. +- A pending user-input gate owns a persistent checkpoint, not a blocked interpreter thread. +- The same answer may be returned repeatedly; a competing answer or stale revision conflicts. +- A completed subtask wait is distinct from a successful child exit. +- Existing successful siblings remain visible when one subtask fails. +- Writes, executable effects and external writes remain under ToolSpec permissions, + the EffectLedger and source-version checks. +- No component may silently broaden a tool's authorization on failure. + +## Important limitations in this branch + +The input/reply gate stores an explicit **step boundary**. It does not yet persist +an arbitrary bytecode interpreter frame. Applications must choose and re-enter +their next Marqdo function explicitly after receiving a verified input answer. +The current source selector relies on a Markdown parser plus Marqdo heading +conventions, not on the compiler's resolved module/class/function AST and symbols. +Host identity inputs are supplied by the caller; production applications must +attest them from their authenticated session, never use model-generated identity. +The parallel wrapper reuses `subtask.run_many` and does not add durable child +lease orchestration. Live provider tests and real 1B-model benchmarking remain open. + +## Required VM/runtime completion: suspended execution + +1. Introduce `WaitingInput` as a scheduler state, distinct from terminal failure. + Save the logical run, program counter at a safe suspension boundary, bound + inputs, variable snapshot, module and tool digests, and effect watermark. +2. Resume via a new attempt linked to the original logical run, but never + automatically repeat committed effects. Preserve cancellation and budget. +3. The resume endpoint must be atomic (revision CAS), authenticate principal + and workspace, verify source and tool schema revisions, and deduplicate + repeated reply requests. Do not trust IDs inside model text. +4. Handle interrupted worker, partial snapshot, stale input, invalid choice and + unknown external write as separate outcomes. Treat unknown writes as + reconciliation-required; do not invent exactly-once guarantees. +5. Persist only serializable language values at declared safe points. If a + foreign kernel, socket or native handle is live, explicitly refuse + transparent frame recovery and preserve a safe step-level restart option. + +## Required durable parallel execution + +A parent dispatches child `.mq.md` functions using registered paths, grants +minimal capabilities, shares budget and rate limits, and persists a child task +manifest. Child completion records a status, value ref, output digest and ledger +watermark before the parent merges results. For same-resource writes, use +serialized revisions and explicit commit order. On parent cancellation, stop +new children and request child cancellation; do not assume remote writes rolled +back. On recovery, reconcile child attempts and reuse successful results. + +## Release gates + +| Test | Required observation | +|---|---| +| compiler/import check | All new `.mq.md` functions pass contract checks and execute via ABI | +| small model outputs | Exact, labeled, fenced and numeric options normalize; mixed options fail | +| input gate crash | After checkpoint, reply is committed once; alternate reply conflicts | +| source drift | Original gate cannot resume against changed source revision | +| context isolation | Class/function selectors reject ambiguity and ignore fenced headings | +| concurrent partial | Failed/uncertain child never discards successful siblings | +| unknown write | Neither retry nor recovered child duplicates an unconfirmed effect | +| long-run cancellation | Worker/child task termination preserves usable artifacts and receipts | +| compatibility | Existing `agent.step/plan/run` and workbooks remain callable | +| model evaluation | Tokens/decision, semantic validity, end-to-end completion, recovery overhead | + +Do not merge the branch as a completed runtime refactor until the relevant +runtime gates, including crash injection and multi-worker concurrency, pass.