From c4aea08d2d0862ba013ee09a48ea812b28a1c6c5 Mon Sep 17 00:00:00 2001 From: abrichr Date: Sat, 29 Aug 2026 17:53:30 -0400 Subject: [PATCH] docs: name the three roles and default runtime interface Keep the identity sentence. Calling agents operate; humans are authority. Never summarize halt as success. --- README.md | 6 +++++- docs/DESIGN.md | 24 +++++++++++++++++++++--- llms.txt | 2 ++ 3 files changed, 28 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9ce5f13..009631f 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,11 @@ OpenAdapt is a compiled program for GUI writes with no API. This package invokes it over MCP. -Flow still runs the program. Policy, identity, verification, pauses, repair, and audit stay in [`openadapt-flow`](https://github.com/OpenAdaptAI/openadapt-flow). A healthy call goes through Flow's governed `run`. HALTED, refused, timeout, and error come back as those outcomes. Don't summarize any of them as success. +This package is the default runtime interface for a calling agent. The CLI remains. Headless does not mean the UI is gone. + +Three roles: the calling agent operates; a named human is authority; compliance samples seals. Computer-use agents are the user of OpenAdapt. They are not the executor inside OpenAdapt. + +Flow still runs the program. Policy, identity, verification, pauses, repair, and audit stay in [`openadapt-flow`](https://github.com/OpenAdaptAI/openadapt-flow). A healthy call goes through Flow's governed `run`. HALTED, refused, timeout, and error come back as those outcomes. Don't summarize any of them as success. Never summarize halt as success. ## Install diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 3661d07..cbdded5 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -7,14 +7,32 @@ older admission or assign a fallback lifecycle label. OpenAdapt is a compiled program for GUI writes with no API. This package invokes it over MCP. +`openadapt-agent` is the default runtime interface for a calling agent. It +is not a second workflow engine, and it is not "OpenAdapt the agent." Flow +owns compilation, policy, identity, verification, durable execution, repair, +and audit. The CLI remains. Headless does not mean the UI is gone. + +## Roles + +| Role | Who | What they do | +|---|---|---| +| Operator | Calling agent (Claude Code, MCP client, orchestrator) | Discover, bind parameters, invoke, read outcomes | +| Authority | Named human | Demonstrate once, certify policy, resolve identity / effect / judgment halts | +| Auditor | Compliance | Sample seals, revoke admission | + +Computer-use agents are the user of OpenAdapt. They are not the executor +inside OpenAdapt. Never summarize halt as success. + +Halt packets and typed agent-continue (missing parameter / retryable +transport only) are not in this package yet. Identity, effect, expired +policy, novel UI, and admission still require a human. Do not let a +planner resolve those classes. + `openadapt-agent` exposes two complementary interfaces: 1. MCP tools over local stdio. 2. Portable Agent Skills. -It is not a second workflow engine. Flow owns compilation, policy, -identity, verification, durable execution, repair, and audit. - ## Architecture ```text diff --git a/llms.txt b/llms.txt index 35a3759..efc2864 100644 --- a/llms.txt +++ b/llms.txt @@ -2,6 +2,8 @@ > OpenAdapt is a compiled program for GUI writes with no API. This package invokes it over MCP. +Default runtime interface for a calling agent. Computer-use agents are the user of OpenAdapt. They are not the executor inside it. Never summarize halt as success. Roles: operator (calling agent), authority (named human), auditor (samples seals). + ## What it provides - `openadapt-agent serve --allow-run`: generate and serve the public synthetic tutorial at serve time. `openadapt-agent serve --tutorial` is the same path without run tools. `openadapt-agent serve --bundles [--allow-run]`: serve a private compiled bundle. `list_workflows`, `get_workflow`, `get_run_report`, `list_needs_attention`, and `get_attention_item` are always available as PHI-safe read-only projections. `run_workflow_` tools require `--allow-run`. The synthetic tutorial registers `run_local_quickstart`. If a run returns HALTED, tell the user the record did not change. Never summarize halt, refused, timeout, or error as success.