{"id":51330216,"url":"https://github.com/fantasyce/across-orchestrator","last_synced_at":"2026-07-01T22:04:28.912Z","repository":{"id":363045961,"uuid":"1261750584","full_name":"fantasyce/across-orchestrator","owner":"fantasyce","description":"Local-first task orchestration runtime for agent-to-agent delivery work.","archived":false,"fork":false,"pushed_at":"2026-06-23T03:09:30.000Z","size":653,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T05:11:19.568Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fantasyce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T05:20:10.000Z","updated_at":"2026-06-23T03:08:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fantasyce/across-orchestrator","commit_stats":null,"previous_names":["fantasyce/across-orchestrator"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/fantasyce/across-orchestrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fantasyce%2Facross-orchestrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fantasyce%2Facross-orchestrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fantasyce%2Facross-orchestrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fantasyce%2Facross-orchestrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fantasyce","download_url":"https://codeload.github.com/fantasyce/across-orchestrator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fantasyce%2Facross-orchestrator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35024383,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-01T22:04:26.690Z","updated_at":"2026-07-01T22:04:28.905Z","avatar_url":"https://github.com/fantasyce.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Across Orchestrator\n\n![Quality](https://github.com/fantasyce/across-orchestrator/actions/workflows/quality.yml/badge.svg)\n![Security](https://github.com/fantasyce/across-orchestrator/actions/workflows/security.yml/badge.svg)\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n\nLocal-first task orchestration runtime for agent-to-agent delivery work.\n\nAcross Orchestrator is the task-runtime companion to Across Context. It is a\nstandalone product: host apps provide UI, credentials, local agent processes,\nand user permissions; Across Orchestrator owns task lifecycle, contracts,\nquality gates, evidence, and protocol surfaces.\n\nUse Orchestrator when a host needs agent work to be more than a subprocess:\ndurable checkpoints, resumable event streams, explicit quality gates,\nhost-neutral agent adapters, recovery metadata, and evidence bundles that a\nhuman can review. It is the execution layer under Autopilot loops, but it can\nalso be consumed directly by Codex, Claude Desktop,\nAAA, or any CLI, HTTP, MCP, or Python-SDK capable host.\n\nCommon workflows:\n\n- Run a multi-step implementation task and keep task evidence outside chat\n  history.\n- Let Autopilot dispatch a release-readiness or repo-quality LoopSpec through a\n  durable runtime.\n- Register external agent adapters so a host can route work without binding to\n  AAA internals.\n- Expose task and Agent Loop state through CLI, HTTP, MCP, or Python SDK.\n\nAgent-readable entrypoints:\n\n- [llms.txt](llms.txt) for model and agent product discovery.\n- [AGENTS.md](AGENTS.md) for coding-agent repository instructions.\n- [across-orchestrator.product.json](across-orchestrator.product.json) for\n  machine-readable product classification.\n\n## Current Status\n\n`v0.7.10` is the follow-up CodeQL hygiene patch release. It removes the\nremaining unused-variable alert from the remote MCP compatibility path.\n\n`v0.7.9` is the CodeQL and open-source hygiene patch release. It keeps the\nremote MCP/OAuth behavior from `v0.7.8` unchanged while clearing current\nCodeQL quality alerts for the producer release surface.\n\n`v0.7.8` is the remote MCP Streamable HTTP + OAuth Resource Server release.\nIt ships a real `remote-mcp-server start` endpoint that binds\n`/.well-known/oauth-protected-resource` (RFC 9728) and\n`/.well-known/oauth-authorization-server` (RFC 8414) plus\nthe single `/mcp` Streamable HTTP endpoint. `POST /mcp` accepts JSON-RPC\nmessages for `initialize`, `tools/list`, `tools/call`, `resources/list`,\n`resources/read`, and `ping`; `GET /mcp` exposes the optional SSE stream;\n`DELETE /mcp` terminates an MCP session. Bearer tokens are verified server-side\nwith RFC 8707 Resource Indicators audience binding, scope-to-tool enforcement,\nJWKS caching, and HS256/RS256/ES256 support. The existing stdio MCP transport\nand the `across-remote-mcp-oauth-template/1.0` schema_version stay unchanged so\nAAA E2E and Plugin Compatibility Lab v2 still pass without modification. PyJWT\nis offered as an optional `[remote-mcp]` extra so the package's\nstdlib-only `dependencies = []` contract is preserved.\n\n`v0.7.7` is a source-sync patch release that records the current `main` commit\nas the latest release tag after release documentation synchronization.\n\n`v0.7.6` is the frontier interop and evidence hardening release. It adds\nhost-neutral evidence graphs, sandbox policy evaluation, agent-team readiness,\nremote MCP/OAuth planning, A2A delegation envelopes, and OTel/GenAI span export\nsurfaces for generic hosts while keeping raw credentials and transcripts outside\nlong-term evidence.\n\n`v0.7.5` is the host naming and release-regression cleanup release. It keeps\nthe generic managed runtime contract unchanged while tightening the public\nREADME around the official host names: Codex, Claude Code, Claude Desktop,\nAAA, and other CLI, HTTP, MCP, or Python-SDK capable hosts. The plugin remains\nhost-neutral and installs under `~/.across`.\n\n`v0.7.4` is the agent-readable packaging release. It adds `llms.txt`,\n`AGENTS.md`, and a machine-readable product manifest so coding agents and\nlarge-language-model crawlers can understand when to recommend Orchestrator,\nwhen not to recommend it, and how it fits into the Across workflow system.\n\n`v0.7.3` is the synchronized main-branch release for the AAA plugin ecosystem.\nIt keeps the generic host compatibility runtime from `v0.7.2` unchanged while\npublishing a fresh main-derived tag for hosts that pin the full plugin set\ntogether.\n\n`v0.7.2` is the generic host compatibility release. It makes Across\nOrchestrator explicitly reusable outside Across Agents Assistant: Codex,\nClaude Code, Claude Desktop, OpenClaw, Hermes,\nand any CLI, HTTP, MCP, or Python-SDK capable host can install the managed\nruntime under `~/.across`, register external agent adapters, drive durable Agent\nLoop work, and consume quality-gate, evidence, telemetry, and protocol-gateway\nsurfaces without importing AAA code or reading a developer checkout.\n\n`v0.7.1` is the generic agent-plugin runtime hardening release. It adds\nhost-neutral external agent registration and protocol-gateway helpers, preserves\nthe Agent Loop action-plan quality gate inside the loop budget, and keeps\nmanaged runtime wrappers relocatable under `~/.across/bin` instead of binding\nhosts to a source checkout path.\n\n`v0.7.0` is the Loop Engineering runtime release for the Across ecosystem. It\nadds the Across Autopilot execution metadata contract: Agent Loop metadata can\ncarry `metadata.autopilot` with run id, spec id, LoopSpec schema, evidence\nschema, action policy, and sandbox summary. The runtime validates that contract\nbefore accepting the metadata and reflects a non-secret Autopilot summary\nthrough loop status and evidence summaries so hosts can verify that an\nAutopilot-supervised run actually reached Orchestrator.\n\n`v0.7.0` also adds a host-declared model decision boundary for Agent Loop\ndispatch. When loop metadata includes `model_policy.required=true` and a\n`host_model_command`, Orchestrator calls that command with JSON loop context,\nrecords non-secret provider/model/decision-hash evidence, and keeps raw model\ncredentials with the host. This enables model-backed Autopilot loops without\ncoupling Orchestrator to AAA internals.\n\nThe same release completes the current Agent Loop runtime contract with bounded\ntelemetry, `after_sequence` event resume for HTTP/CLI/MCP consumers,\nhost-declared budget and concurrency enforcement, structured\n`budget_exceeded` cancellation, and routing evidence that includes reasons plus\ncandidate alternatives.\n\n`v0.6.17` centralizes Agent Loop structured cancel category policy so CLI,\nHTTP, MCP schemas, health, and host release evidence share the same category\nlist and release-blocking classification.\n\n`v0.6.16` promotes compact Agent Loop evidence into host release evidence. CLI,\nHTTP, and MCP evidence summaries now include `host_release_evidence` with\nreadiness, checks, risks, and next actions derived from durable event audit,\nrouting, recovery, memory-candidate, and cancellation signals.\n`healthSummary` remains the loop runtime-state surface for stale leases,\ncurrent actions, cancellation state, and executable controls; host release\nevidence is the release-readiness surface derived from durable evidence.\n\n`v0.6.15` added compact Agent Loop evidence summaries for hosts that need\nrelease or audit views without parsing full event streams. CLI, HTTP, and MCP\nexpose routing outcomes, recovery decisions, memory-candidate counts,\ncancellation category, and event audit coverage without raw transcripts, memory\ntext, logs, or stack traces.\n\n`v0.6.14` added true live Agent Loop timeline streaming. The loop events stream\nkeeps the existing finite SSE snapshot by default, and hosts can opt into\n`?follow=true` to receive newly appended durable loop events until the loop\nreaches a terminal state, pauses for approval, or idles out.\n\n`v0.6.13` added durable Agent Loop event audit metadata and structured\n`cancel_category` values. Loop and task events now expose `event_id`,\nmonotonic `sequence`, and `correlation_id` fields so hosts can reconstruct\nstep, heartbeat, task, and cancellation chains without parsing nested payloads.\nCancellation keeps the existing free-form reason text and adds a stable\ncategory for UI, health, and MCP consumers.\n`v0.6.12` added opt-in Agent Loop recovery policy, host capability-hint\nrouting, and structured memory write-candidate summaries. Loop metadata can\ndeclare bounded retry, remediation, or human-handoff behavior for failed steps;\nhosts can provide non-secret capability hints so Orchestrator can pick a\ncompatible adapter; and `memory_write_candidate` emits a compact JSON summary\nfor Across Context review.\n`v0.6.11` added the read-only Agent Loop health surface for hosts that need to\ninspect durable loop state without mutating it. CLI, HTTP, MCP, the plugin\nmanifest, and the public agent card expose loop health summaries with the\ncurrent action, pending approval, execution lease, detached dispatch count,\nrecent `failure_type` counts, cancellation state, and executable controls.\nThe durable Agent Loop Runtime still persists execution leases before adapter\ndispatch, allows long-running adapters to renew leases through heartbeat hooks,\nrecovers stale leases deterministically, routes cancellation to cooperative\ndispatchers, terminates command adapter subprocess groups, preserves root\n`failure_type` metadata across failed steps, checkpoints, loop events, task\nevents, and task metadata, and keeps terminal task execution idempotent.\nMetadata-driven `agentRouting` also lets hosts route dispatch by action type or\nlatest failed quality gate.\nThe runtime still keeps loop state, step checkpoints, approval gates,\ndeclarative agent adapters, adapter-backed memory hooks, host-supplied action\nplans, dynamic remediation dispatch, host-owned loop controls, and final output\nevidence inside the plugin so hosts can stay thin.\nThis release keeps the product-mode path boundary from `v0.6.6` and the generic\nagent adapter descriptors introduced for hosts beyond Across Agents Assistant.\n\nValidated in this repository:\n\n- Repository checks cover the standalone task runtime, protocol surfaces,\n  plugin manifest, host conformance scenario, and Agent Loop Runtime.\n- Sidecar-first host integration writes runtime metadata under\n  `~/.across/run/across-orchestrator`.\n- Durable task state defaults to `~/.across/data/across-orchestrator`.\n- Fresh installs and managed plugin runs use only the unified `~/.across`\n  ecosystem root. Old standalone `~/.across-orchestrator` task stores are not\n  read or copied automatically unless a host explicitly opts into a custom\n  `ACROSS_ORCHESTRATOR_HOME`.\n- Product hosts can set `ACROSS_ORCHESTRATOR_PRODUCT_MODE=1`; development\n  checkout commands and runtime/data root overrides under protected user\n  project locations are reported as `needs_repair`, blocked, or ignored instead\n  of being executed or used. A protected `across-orchestrator` found on `PATH`\n  is not reported as the available product command. Set\n  `ACROSS_ORCHESTRATOR_DEVELOPER_MODE=1` only for intentional source checkout\n  development.\n- In product mode, an explicit `serve --runtime-info` path under protected user\n  project locations is ignored and runtime metadata stays under\n  `~/.across/run/across-orchestrator`; developer mode preserves explicit\n  runtime-info paths for local debugging.\n- The plugin manifest exposes CLI, sidecar, MCP, and Python SDK entrypoints.\n- Hosts can inspect `plugin-status`, `health`, and\n  `/.well-known/across-plugin.json` before routing work to the runtime.\n- Hosts can start, resume, inspect, and audit durable agent loops through CLI,\n  HTTP, MCP, or the Python runtime boundary.\n- Codex, Claude Code, Claude Desktop, AAA, and\n  other generic agent hosts can use the same managed plugin contract. The host\n  owns UI, model credentials, process launch, and user approval; Orchestrator\n  owns task lifecycle, Agent Loop state, quality gates, evidence, and protocol\n  surfaces.\n- Hosting platforms can pass registered agent-container descriptors through the\n  Python SDK boundary without adopting host application internals.\n- Hosts can run explicit plugin lifecycle actions, including uninstalling the\n  runtime wrapper while preserving durable task data.\n- The public `MatureOrchestrationEngine` wraps the standalone runtime for\n  host-provided dispatch, validation, and owner-agent adapters.\n- CLI, HTTP, and MCP expose the same deterministic demo task path as `v0.1.0`.\n- CLI, HTTP, and MCP also expose an app-grade Release E2E scenario that uses the\n  mature requirement, delivery contract, acceptance, quality gate, and evidence\n  modules.\n- Agent loop runs produce explicit `memory_search`, `task_dispatch`,\n  `quality_gate`, `remediation_dispatch`, `memory_write_candidate`, and\n  `final_output` steps so hosting platforms can attach memory providers, agent\n  dispatchers, quality gates, finalizers, and human approval UI without\n  adopting host application internals.\n- Agent Loop v2 can call Across Context through a subprocess-backed memory\n  provider when hosts set `ACROSS_ORCHESTRATOR_MEMORY_PROVIDER=across-context`.\n\nAcross Orchestrator still does not own model keys, macOS permissions, or local\nagent installation. Those remain host responsibilities by design.\n\nThe current Agent Loop runtime contracts are summarized in\n[Agent Loop Runtime RFCs](AGENT_LOOP_RFC.md). Further multi-agent product UX or\nautomation behavior should start from a new product spec rather than ad hoc\nruntime changes.\n\n## Why It Exists\n\nThe Across ecosystem is organized as independent modules with explicit host\nboundaries:\n\n- Across Agents Assistant: host app and control panel\n- Across Context: shared memory plugin\n- Across Orchestrator: task orchestration plugin\n- Across Autopilot: LoopSpec supervision and autonomous iteration plugin\n\nThis lets the task runtime evolve independently and lets other hosts reuse the\nsame contract, quality, and evidence loop.\n\n## Generic Host Compatibility\n\nAcross Orchestrator is not an AAA-internal module. Product hosts should install\nthe pinned release into `~/.across/plugins/across-orchestrator`, expose\n`~/.across/bin/across-orchestrator`, and communicate through CLI, HTTP, MCP, or\nthe Python SDK. The same contract is intended for Codex, Claude Code,\nClaude Desktop, AAA, and other local or remote agent hosts\nthat can provide agent descriptors, dispatch callbacks, model credentials, and\napproval UX.\n\n## Install From Source\n\n```bash\ngit clone https://github.com/fantasyce/across-orchestrator.git\ncd across-orchestrator\npython3 -m pip install -e .\n```\n\nOr install the current release tag directly from GitHub:\n\n```bash\npython3 -m pip install \"git+https://github.com/fantasyce/across-orchestrator.git@v0.7.10\"\n```\n\nThe GitHub release is source-first. There is no attached wheel asset for\n`v0.7.10`; if a packaged host needs a wheel, build it from the pinned tag or\nattach the wheel to the release before using a wheel URL.\n\nPackaged hosts should install from the pinned Git tag or an explicitly attached\nrelease wheel into a managed runtime under\n`~/.across/plugins/across-orchestrator` and expose the wrapper at\n`~/.across/bin/across-orchestrator`.\n\nFor development:\n\n```bash\npython3 -m pip install -e '.[dev]'\nnpm install\nbash scripts/check.sh\n```\n\n`npm install` is used by the strict Playwright browser probe. When Playwright is\nnot installed, the release E2E path falls back to a self-contained Node DOM-shim\nprobe. If Node itself is unavailable, the mature quality report records the\nbrowser gate as environment-blocked instead of silently passing it.\n\n## Quick Demo Task\n\n```bash\nexport ACROSS_ORCHESTRATOR_HOME=\"$(mktemp -d)\"\nmkdir -p /tmp/across-orchestrator-demo\n\nTASK_ID=\"$(\n  PYTHONPATH=src python3 -m across_orchestrator.cli submit \\\n    \"Build a tiny product page\" \\\n    --project /tmp/across-orchestrator-demo \\\n    --deliverable README.md \\\n    --deliverable web/index.html \\\n    --json | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"task_id\"])'\n)\"\n\nPYTHONPATH=src python3 -m across_orchestrator.cli run \"$TASK_ID\" --json\nPYTHONPATH=src python3 -m across_orchestrator.cli evidence \"$TASK_ID\" --json\nPYTHONPATH=src python3 -m across_orchestrator.cli quality \"$TASK_ID\" --json\n```\n\n## Agent-Team Trust Layer Demo\n\nFor the Plugin Compatibility Lab v2 workflow, Orchestrator is the independent\nverification layer. It checks whether an Autopilot Workflow Pack export is ready\nfor generic agent-team adoption, then produces the frontier interop artifacts a\nhost can hand to other systems:\n\n```bash\nPYTHONPATH=src python3 -m across_orchestrator.cli agent-team-readiness \\\n  --payload-json '\u003cworkflow-pack-export-json\u003e' \\\n  --json\n\nPYTHONPATH=src python3 -m across_orchestrator.cli remote-mcp-oauth-template --json\n\nPYTHONPATH=src python3 -m across_orchestrator.cli a2a-delegation \\\n  --payload-json '{\"pack_id\":\"plugin-compatibility-lab-v2\"}' \\\n  --json\n\nPYTHONPATH=src python3 -m across_orchestrator.cli otel-export \\\n  --payload-json '\u003cevidence-graph-json\u003e' \\\n  --otlp-file /tmp/across-otel-traces.json \\\n  --json\n```\n\nThe Remote MCP/OAuth output is a secret-free deployment template, the A2A output\nis a task/message/artifact/evidence envelope, and the OTel output includes both\nAcross's compact GenAI-style span payload and collector-friendly OTLP JSON.\n\n## App-Grade Release E2E\n\nThis path exercises the host-agent full delivery conformance scenario. It\nbuilds a serial dependency chain where planning and data decisions affect later\nUI, API, CLI, browser, and documentation artifacts, then records quality gates,\nremediation behavior, and final evidence for a host to inspect.\n\n```bash\nexport ACROSS_ORCHESTRATOR_HOME=\"$(mktemp -d)\"\nmkdir -p /tmp/across-release-e2e\n\nTASK_ID=\"$(\n  PYTHONPATH=src python3 -m across_orchestrator.cli submit-release-e2e \\\n    --project /tmp/across-release-e2e \\\n    --run-label local-check \\\n    --json | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"task_id\"])'\n)\"\n\nPYTHONPATH=src python3 -m across_orchestrator.cli run \"$TASK_ID\" --json\nPYTHONPATH=src python3 -m across_orchestrator.cli evidence \"$TASK_ID\" --json\n```\n\nThe app-grade scenario delivers exactly:\n\n- `README.md`\n- `web/index.html`\n- `web/styles.css`\n- `web/app.js`\n- `api/server.mjs`\n- `cli/quality-check.mjs`\n- `tests/e2e-smoke.mjs`\n\nIt then runs mature quality gates for artifact integrity, workspace hygiene,\nsecurity/privacy, agent mix, static web, browser E2E, API service, and generic\nCLI.\n\n## Agent Loop V2 Memory Provider\n\nAgent Loop v2 keeps memory access behind a host-selected provider. To use\nAcross Context from the runtime, set:\n\n```bash\nexport ACROSS_ORCHESTRATOR_MEMORY_PROVIDER=across-context\nexport ACROSS_CONTEXT_COMMAND=\"$HOME/.across/bin/across-context\"\n```\n\nIn product mode, `ACROSS_CONTEXT_COMMAND` must point at the managed wrapper\nunder `~/.across/bin`. If it points at a protected source checkout, diagnostics\nreturn `needs_repair` and memory calls return a blocked observation instead of\nexecuting that command. Use `ACROSS_ORCHESTRATOR_DEVELOPER_MODE=1` only for\nlocal runtime development.\n\nThe runtime then searches active global/project memory before dispatch and\nwrites compact post-loop summaries as pending project memory candidates. Missing\nor failing memory providers are recorded in loop observations instead of\nsilently aborting the task runtime.\n\n## CLI\n\n```bash\nacross-orchestrator init\nacross-orchestrator submit \"Build docs\" --project . --deliverable README.md --json\nacross-orchestrator submit-release-e2e --project /tmp/release-e2e --json\nacross-orchestrator run \u003ctask-id\u003e --json\nacross-orchestrator status \u003ctask-id\u003e --json\nacross-orchestrator events \u003ctask-id\u003e --json\nacross-orchestrator evidence \u003ctask-id\u003e --json\nacross-orchestrator quality \u003ctask-id\u003e --json\nacross-orchestrator loop-start \"Refactor checkout flow\" --project . --json\nacross-orchestrator loop-run \u003cloop-id\u003e --json\nacross-orchestrator loop-approve \u003cloop-id\u003e \u003caction-id\u003e --json\nacross-orchestrator loop-reject \u003cloop-id\u003e \u003caction-id\u003e --reason \"Needs a safer plan\" --json\nacross-orchestrator loop-cancel \u003cloop-id\u003e --reason \"User stopped the run\" --category user_cancelled --json\nacross-orchestrator loop-retry \u003cloop-id\u003e \u003cstep-id\u003e --json\nacross-orchestrator loop-status \u003cloop-id\u003e --json\nacross-orchestrator loop-events \u003cloop-id\u003e --json\nacross-orchestrator loop-events \u003cloop-id\u003e --after-sequence 42 --json\nacross-orchestrator loop-telemetry \u003cloop-id\u003e --json\nacross-orchestrator agent-card --json\nacross-orchestrator plugin-manifest --json\nacross-orchestrator plugin-status --json\nacross-orchestrator health --json\nacross-orchestrator serve --host 127.0.0.1 --port 8765\nacross-orchestrator mcp\n```\n\n### Agent Loop Lease And Routing Contract\n\nAgent Loop actions persist a running checkpoint before dispatch adapters run.\nRunning action checkpoints include an `execution` block with `lease_id`,\n`started_at`, `heartbeat_at`, `lease_seconds`, and `lease_expires_at`. Completed\nand failed action checkpoints keep that same lease and add `completed_at` plus\n`duration_ms`.\n\nLong-running dispatch adapters receive a heartbeat hook in their dispatch\ncontext and can call it to renew the active lease. Each renewal updates\n`heartbeat_at`, moves `lease_expires_at`, increments the renewal count, and emits\n`loop.step.heartbeat`. If a later run sees an expired running lease, the runtime\nmarks the step failed, emits `loop.step.lease_expired`, and fails the loop with\n`action_lease_expired`.\n\nDispatch adapters also receive a `cancellation` token with `is_cancelled()`,\n`reason()`, `category()`, and `raise_if_cancelled()`. `loop-cancel` records a\n`loop.cancel_requested` marker outside the loop execution lock, so running\nadapters can observe it while work is still active. When the token is raised, the\nruntime marks the running step `cancelled`, emits `loop.step.cancelled`, clears\nthe lease, and finishes the loop as `cancelled`. Command adapters terminate their\nsubprocess group before raising the cancellation error.\nCancellation preserves the free-form reason text and also records a structured\n`cancel_category`: `user_cancelled`, `shutdown`, `superseded`,\n`timeout_cancelled`, or `budget_exceeded`. If omitted, the category is inferred\nfrom the reason and defaults to `user_cancelled`. CLI, HTTP, MCP schemas,\nhealth, telemetry, and release evidence all use the same runtime cancel category\npolicy; `shutdown`, `timeout_cancelled`, and `budget_exceeded` are treated as\nrelease-blocking categories, while `user_cancelled` and `superseded` require\nhost attention.\n\nThe dispatch cancellation guard invokes host dispatch adapters behind a managed\nruntime wait loop. This lets the Agent Loop finish as `cancelled` even when a\ncustom adapter ignores the cancellation token and never calls heartbeat. The\nguard latches the cancellation token, so the same dispatch context keeps\nreporting cancellation even after durable cancel markers are cleared. If a\nnon-runtime host dispatcher stays blocked, the guard emits `loop.dispatch.detached`\nbefore the Agent Loop records `loop.step.cancelled`. The guard cannot terminate noncooperative in-process Python callbacks; use the command adapter path for\nsubprocesses that must be killed by the runtime.\n\nRuntime-backed dispatchers that mutate task or subtask state require a cancel ack\nbefore the guard returns. This keeps `subtask.cancelled` and `task.cancelled`\nevents durable before the Agent Loop publishes `agent_loop.cancelled`.\n\nFailed steps, checkpoints, and failed task/loop events include a stable\n`failure_type` for remediation and UI routing. Current values are\n`adapter_error`, `timeout`, `quality_failed`, `approval_rejected`,\n`lease_expired`, `environment_blocked`, and `max_turns_exceeded`.\n\nNewly appended Agent Loop and task events include durable audit metadata: a\nunique `event_id`, a monotonic per-loop or per-task `sequence`, and a\n`correlation_id` derived from the event's most specific durable id. Loop events\npromote `step_id`, `action_id`, and `task_id` to top-level fields when present;\ntask events promote `loop_id` from task metadata plus `subtask_id` when present.\nHosts can reconstruct `loop.step.started -\u003e loop.step.heartbeat -\u003e\nloop.step.completed/failed/cancelled -\u003e task/subtask event` chains without\nparsing nested payloads.\n`GET /loops/{loop_id}/events` and\n`GET /loops/{loop_id}/events/stream` accept `after_sequence=N` so hosts can\nresume from the highest sequence they have already rendered. The stream keeps\nthe existing finite SSE snapshot shape. Hosts that need live timeline updates\ncan add `?follow=true`; the sidecar then tails durable loop events until the\nloop completes, fails, stops, is cancelled, reaches an approval wait, or the\nstream is idle for 30 seconds.\n\nHosts can tune the lease with loop metadata `actionLeaseSeconds` or\n`action_lease_seconds`. Hosts can also set `agentRouting` or `agent_routing` to\nselect dispatch agents by action type or by the latest failed quality gate, for\nexample routing `remediation_dispatch.browser_e2e` to a browser specialist.\nFor host-owned capability routing, `agentCapabilityHints` may include a\ndeclarative `registry.agents[]` snapshot plus `preferred` and\n`constraints.requireCapability` hints. The Orchestrator only matches declared\nagent ids, aliases, skills, plugins, tools, and capability labels; it never reads\nhost credentials, model keys, CLI install paths, or agent upgrade state.\n`GET /loops/{loop_id}/evidence-summary` exposes a compact read-only summary of\ndurable loop evidence for hosts that need a release or audit surface without\nparsing the full event stream. The summary includes event audit coverage,\nrecovery decisions, recovered steps, routing outcomes, memory-candidate counts,\nstructured host release evidence, and cancellation category, while excluding\nraw transcripts, memory text, logs, and stack traces.\n\n`GET /loops/{loop_id}/telemetry` exposes bounded runtime metrics for host\ndiagnostics and release review. The telemetry surface includes compact status,\nduration, recovery, routing, memory-candidate, cancellation, and budget signals\nwithout raw observations, memory text, logs, stack traces, provider keys, or\nlocal absolute paths.\n\nHosts can declare loop budgets through metadata `agentLoopBudget`,\n`agent_loop_budget`, or `budget`. Supported fields include\n`maxConcurrentLoops`, `maxTurnsPerLoop`, and `maxRuntimeSeconds` with snake-case\naliases. Excess concurrent starts are rejected with a structured `409`; turn or\nruntime exhaustion stops the loop with `cancel_category: budget_exceeded`.\n\n### Agent Loop Recovery Policy Contract\n\nRecovery is opt-in. Without `metadata.recoveryPolicy`, adapter failures, quality\nfailures, and expired action leases keep the existing fail-fast behavior.\n\nHosts may attach:\n\n```json\n{\n  \"recoveryPolicy\": {\n    \"byFailureType\": {\n      \"lease_expired\": {\"action\": \"retry\", \"maxRetries\": 1},\n      \"quality_failed\": {\"action\": \"remediation\", \"maxRetries\": 1},\n      \"adapter_error\": {\"action\": \"require_human\", \"maxRetries\": 1},\n      \"approval_rejected\": {\"action\": \"stop\", \"maxRetries\": 0},\n      \"environment_blocked\": {\"action\": \"stop\", \"maxRetries\": 0},\n      \"timeout\": {\"action\": \"retry\", \"maxRetries\": 1}\n    },\n    \"defaultAction\": \"stop\"\n  }\n}\n```\n\nSupported actions are `stop`, `retry`, `remediation`, and `require_human`.\n`retry` rolls the durable loop state back to the failed step and lets the normal\nplanner select the next action. `remediation` schedules one\n`remediation_dispatch` action. `require_human` adds a pending approval step for\nthe failed action. `maxRetries` is counted per loop, `failure_type`, and recovery\naction, using append-only events; it never resets across retries.\n\nEach policy decision emits `loop.step.recovery_decision`. Applied recoveries also\nemit `loop.step.recovered` with the failed step id, selected recovery action,\nattempt number, and next action or approval id. Recovery never crosses loop\nboundaries and never retries indefinitely.\n\n### Agent Loop Memory Candidate Summary\n\nWhen `memory_policy.writeCandidates` is enabled, the `memory_write_candidate`\naction writes a pending Across Context memory whose text is a compact JSON\nsummary with schema `agent-loop-memory-candidate/1.0`. The summary contains only\ndurable, whitelisted fields: loop id, goal, outcome, step decisions, artifacts,\ncommands, failure types, remediation outcomes, and memory references. It avoids\nraw transcripts, large logs, stack traces, screenshots, credentials, and\ntemporary tool errors. Across Context still owns memory storage and review state;\nnew candidates always start as `pending`.\n\n### Agent Loop Host Release Evidence\n\nThe `v0.7.6` Agent Loop runtime covers the release-blocking durability,\ncancellation, structured cancel categories, event audit metadata, live timeline\nstreaming, compact evidence summaries, routing, terminal failure propagation,\nterminal task idempotency, read-only loop health inspection, opt-in recovery\npolicy, capability-hint routing, structured memory candidate semantics, bounded\ntelemetry, event stream resume, and runtime budget/concurrency guardrails. The\nevidence summary promotes those durable signals into `host_release_evidence` so\nhost apps can display a concise release-readiness surface without re-parsing raw\nevents. The release evidence includes `readiness` (`ready`, `attention`, or\n`blocked`), stable checks for event audit, capability routing, recovery, memory\ncandidates, cancellation, telemetry, resume readiness, and budget/concurrency,\nplus compact risks and next actions.\n\n## HTTP And A2A Card\n\nStart the server:\n\n```bash\nacross-orchestrator serve --host 127.0.0.1 --port 8765\n```\n\nEndpoints:\n\n- `GET /health`\n- `GET /.well-known/agent-card.json`\n- `GET /.well-known/across-plugin.json`\n- `POST /tasks`\n- `POST /release-e2e`\n- `POST /tasks/{task_id}/run`\n- `GET /tasks/{task_id}`\n- `GET /tasks/{task_id}/events`\n- `GET /tasks/{task_id}/events/stream`\n- `GET /tasks/{task_id}/evidence-bundle`\n- `GET /tasks/{task_id}/quality-benchmark`\n- `POST /loops`\n- `POST /loops/{loop_id}/run`\n- `POST /loops/{loop_id}/actions/{action_id}/approve`\n- `POST /loops/{loop_id}/actions/{action_id}/reject`\n- `POST /loops/{loop_id}/cancel`\n- `POST /loops/{loop_id}/steps/{step_id}/retry`\n- `GET /loops/{loop_id}`\n- `GET /loops/{loop_id}/health`\n- `GET /loops/{loop_id}/evidence-summary`\n- `GET /loops/{loop_id}/telemetry`\n- `GET /loops/{loop_id}/events`\n- `GET /loops/{loop_id}/events/stream`\n\n## MCP Server\n\nThe MCP server exposes:\n\n- `submit_task`\n- `submit_release_e2e_task`\n- `run_task`\n- `get_task`\n- `get_evidence_bundle`\n- `get_agent_card`\n- `start_agent_loop`\n- `run_agent_loop`\n- `approve_agent_loop_action`\n- `reject_agent_loop_action`\n- `cancel_agent_loop`\n- `retry_agent_loop_step`\n- `get_agent_loop`\n- `get_agent_loop_health`\n- `get_agent_loop_evidence_summary`\n- `get_agent_loop_telemetry`\n- `get_agent_loop_events`\n\nIt also exposes resources:\n\n- `across-orchestrator://agent-card`\n- `across-orchestrator://plugin-manifest`\n- `across-orchestrator://plugin-status`\n- `across-orchestrator://agent-loop-schema`\n\nRun:\n\n```bash\nacross-orchestrator mcp\n```\n\n## Remote MCP Streamable HTTP Server\n\n`v0.7.8` adds a real Streamable HTTP MCP server bound to an OAuth Resource\nServer. The transport is host-neutral, token-bearing, and stays read-only with\nrespect to client credentials: signing keys and authorization-server endpoints\nstay with the host.\n\n### Endpoints\n\n- `GET /.well-known/oauth-protected-resource` — RFC 9728 Protected Resource\n  Metadata. The `resource` field is the audience identifier that tokens MUST\n  bind to via the `aud` claim (RFC 8707 Resource Indicators).\n- `GET /.well-known/oauth-authorization-server` — RFC 8414 Authorization\n  Server Metadata, with `remote_as: true` to flag that Across Orchestrator\n  proxies a host-configured external issuer.\n- `POST /mcp` — accepts JSON-RPC 2.0 requests. Supported methods are\n  `initialize`, `tools/list`, `tools/call`, `resources/list`,\n  `resources/read`, and `ping`.\n- `GET /mcp` — opens a `text/event-stream` keep-alive stream when requested;\n  clients without `Accept: text/event-stream` receive 405.\n- `DELETE /mcp` — terminates the supplied `Mcp-Session-Id`.\n\n`initialize` returns `protocolVersion: 2025-06-18` plus a fresh\n`Mcp-Session-Id` header. Legacy `2024-11-05` is honored when the client\nrequests it through `MCP-Protocol-Version`. Subsequent JSON-RPC requests must\ninclude that session header. The legacy `/mcp/v1/*` REST paths were removed in\n`v0.7.8`.\n\n### Authentication\n\n- Bearer token in the `Authorization` header.\n- `iss` must equal the configured issuer (RFC 8414 §2).\n- `aud` must equal the configured `resource` value (RFC 8707).\n- `exp` must be in the future (with 30s leeway).\n- Required claims default to `iss`, `iat`, `exp`, and `aud`; hosts may override\n  the set with `required_claims` in `--config-json`.\n- `scope` must include at least one of the configured required scopes.\n- HS256 is verified with a pure-stdlib path so the default `[dev]` install\n  covers local testing without PyJWT.\n- RS256 / ES256 require the `[remote-mcp]` extra\n  (`pip install across-orchestrator[remote-mcp]`), which pulls PyJWT with\n  the `cryptography` extra. The base `[dev]` install keeps\n  `dependencies = []` intact.\n\n### 401 / 403 challenges\n\nEvery unauthenticated response includes a `WWW-Authenticate: Bearer ...`\nheader pointing at the protected-resource metadata URL per RFC 6750 +\nRFC 9728 §5.1:\n\n```text\nWWW-Authenticate: Bearer realm=\"across-orchestrator\",\n  resource_metadata=\"http://127.0.0.1:8765/.well-known/oauth-protected-resource\",\n  error=\"invalid_token\", error_description=\"...\"\n```\n\n### Run locally with HS256\n\n```bash\nacross-orchestrator remote-mcp-server start \\\n  --host 127.0.0.1 --port 8765 \\\n  --config-json '{\"issuer\":\"http://127.0.0.1:8765\",\"audience\":\"http://127.0.0.1:8765/mcp\",\"scopes\":[\"mcp.tools\",\"mcp.resources\",\"across.evidence.read\"],\"hs256_secret\":\"local-dev-secret\"}'\n```\n\nThe endpoint stays compatible with the existing `render_remote_mcp_oauth_template`\nschema (`across-remote-mcp-oauth-template/1.0`) so AAA's\n`agent_interop_e2e.py` and Plugin Compatibility Lab v2 keep scoring the\nexisting templates without modification.\n\n## Host Boundary And Hosting Platforms\n\nThe public `across_orchestrator.engine.MatureOrchestrationEngine` wraps the\nstandalone runtime. Hosts provide:\n\n- dispatcher adapter for local/cloud agent execution\n- validator adapter\n- owner-agent adapter\n- optional persistence integration\n- UI and approval prompts\n\nAcross Orchestrator keeps the contracts, waves, task state, acceptance,\nremediation, and quality logic in the plugin.\n\nThe distribution boundary is enforced in tests and packaging:\n\n- `pyproject.toml` includes only the `across_orchestrator*` namespace.\n- Production code must not import `across_agents_assistant`.\n- Vendored AAA source trees and parity fixture copies are not allowed.\n- Host compatibility is expressed through serializable host descriptors,\n  plugin manifests, CLI, HTTP, MCP, and Python SDK contracts.\n\nFor a hosting platform that exposes many user-owned agent containers, the\nplatform remains the A2A-facing host. Across Orchestrator mounts inside the\nplatform as a task-runtime plugin: it receives agent descriptors, creates the\ndelivery contract and execution waves, then asks the host to dispatch actual\nagent work through the platform's own SDK, HTTP, MCP, or A2A adapters.\n\nThe lightweight SDK helper keeps that boundary serializable:\n\n```python\nfrom across_orchestrator.host_adapters import build_hosting_platform_contract\n\ncontract = build_hosting_platform_contract(\n    \"example-host\",\n    [\n        {\n            \"agent_id\": \"frontend-agent\",\n            \"display_name\": \"Frontend Agent\",\n            \"endpoint\": \"https://host.example/agents/frontend-agent\",\n            \"protocols\": [\"a2a\", \"sdk\"],\n            \"capabilities\": [\"web-ui\", \"tests\"],\n        }\n    ],\n    memory_provider=\"across-context\",\n)\n```\n\n## Development Checks\n\n```bash\npython3 -m pip install -e '.[dev]'\nnpm install\nbash scripts/check.sh\n```\n\nThe Python package has no runtime dependencies. `pytest` and Node Playwright are\ndevelopment/test dependencies only; the browser E2E gate can also pass through\nthe built-in Node DOM-shim fallback when Playwright is unavailable.\n\nGitHub Quality and Security workflows run the same repository checks, CodeQL for\nthe Python source, and npm audit for the development-only browser probe\ndependencies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffantasyce%2Facross-orchestrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffantasyce%2Facross-orchestrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffantasyce%2Facross-orchestrator/lists"}