Merge origin/main with local UI refactor integration
This commit is contained in:
48
README.md
48
README.md
@@ -20,10 +20,13 @@ TypeScript runtime for deterministic multi-agent execution with:
|
||||
- Runtime events are emitted as best-effort side-channel telemetry and do not affect orchestration control flow.
|
||||
- `AgentManager` is an internal utility used by the pipeline when fan-out/retry-unrolled behavior is required.
|
||||
- Session state is persisted under `AGENT_STATE_ROOT`.
|
||||
- Project state is persisted under `AGENT_PROJECT_CONTEXT_PATH` with schema-versioned JSON (`schemaVersion`) and domains:
|
||||
- Session lifecycle is explicit (`POST /api/sessions`, `POST /api/sessions/:id/run`, `POST /api/sessions/:id/close`) and each session is bound to a target project path.
|
||||
- Session project context is persisted as schema-versioned JSON (`schemaVersion`) with domains:
|
||||
- `globalFlags`
|
||||
- `artifactPointers`
|
||||
- `taskQueue`
|
||||
- each task record stores `taskId`, status, and optional `worktreePath` for task-scoped workspace ownership
|
||||
- conflict-aware statuses are supported (`conflict`, `resolving_conflict`)
|
||||
|
||||
## Deep Dives
|
||||
|
||||
@@ -95,6 +98,7 @@ The UI provides:
|
||||
- graph visualizer with topology/retry rendering, edge trigger labels, node economics (duration/cost/tokens), and critical-path highlighting
|
||||
- node inspector with attempt metadata and injected `ResolvedExecutionContext` sandbox payload
|
||||
- live runtime event feed from `AGENT_RUNTIME_EVENT_LOG_PATH` with severity coloring (including security mirror events)
|
||||
- Claude trace feed from `CLAUDE_OBSERVABILITY_LOG_PATH` (query lifecycle, SDK message types/subtypes, and errors)
|
||||
- run trigger + kill switch backed by `SchemaDrivenExecutionEngine.runSession(...)`
|
||||
- run mode selector: `provider` (real Codex/Claude execution) or `mock` (deterministic dry-run executor)
|
||||
- provider selector: `codex` or `claude`
|
||||
@@ -108,6 +112,9 @@ Provider mode notes:
|
||||
- `provider=codex` uses existing OpenAI/Codex auth settings (`OPENAI_AUTH_MODE`, `CODEX_API_KEY`, `OPENAI_API_KEY`).
|
||||
- `provider=claude` uses Claude auth resolution (`CLAUDE_CODE_OAUTH_TOKEN` preferred, otherwise `ANTHROPIC_API_KEY`, or existing Claude Code login state).
|
||||
- `CLAUDE_MODEL` should be a Claude model id/alias recognized by Claude Code (for example `claude-sonnet-4-6`); `anthropic/...` prefixes are normalized automatically.
|
||||
- `CLAUDE_MAX_TURNS` controls the per-query Claude turn budget (default `2`).
|
||||
- Claude provider runs can emit Claude SDK/CLI internals to stdout and/or NDJSON with `CLAUDE_OBSERVABILITY_*` settings.
|
||||
- UI session-mode provider runs execute directly in orchestration-assigned task/base worktrees; provider adapters do not allocate additional nested worktrees.
|
||||
|
||||
## Manifest Semantics
|
||||
|
||||
@@ -131,9 +138,9 @@ Pipeline edges can route via:
|
||||
Domain events are typed and can trigger edges directly:
|
||||
|
||||
- planning: `requirements_defined`, `tasks_planned`
|
||||
- execution: `code_committed`, `task_blocked`
|
||||
- execution: `code_committed`, `task_ready_for_review`, `task_blocked`
|
||||
- validation: `validation_passed`, `validation_failed`
|
||||
- integration: `branch_merged`
|
||||
- integration: `branch_merged`, `merge_conflict_detected`, `merge_conflict_resolved`, `merge_conflict_unresolved`, `merge_retry_started`
|
||||
|
||||
Actors can emit events in `ActorExecutionResult.events`. Pipeline status also emits default validation/execution events.
|
||||
|
||||
@@ -202,6 +209,30 @@ Notes:
|
||||
- `security.tool.invocation_allowed`
|
||||
- `security.tool.invocation_blocked`
|
||||
|
||||
## Claude Observability
|
||||
|
||||
- `CLAUDE_OBSERVABILITY_MODE=stdout` prints structured Claude query internals (tool progress, system events, stderr, result lifecycle) to stdout as JSON lines prefixed with `[claude-trace]`.
|
||||
- `CLAUDE_OBSERVABILITY_MODE=file` appends the same records to `CLAUDE_OBSERVABILITY_LOG_PATH`.
|
||||
- `CLAUDE_OBSERVABILITY_MODE=both` enables both outputs.
|
||||
- Output samples high-frequency `tool_progress` events to avoid log flooding while retaining suppression counters.
|
||||
- `assistant` and `user` message records are retained so turn flow is inspectable end-to-end.
|
||||
- `CLAUDE_OBSERVABILITY_VERBOSITY=summary` stores compact metadata; `full` stores redacted full SDK message payloads.
|
||||
- `CLAUDE_OBSERVABILITY_INCLUDE_PARTIAL=true` enables and emits sampled partial assistant stream events from the SDK.
|
||||
- `CLAUDE_OBSERVABILITY_DEBUG=true` enables Claude SDK debug mode.
|
||||
- `CLAUDE_OBSERVABILITY_DEBUG_LOG_PATH` writes Claude SDK debug output to a file (also enables debug mode).
|
||||
- In UI/provider mode, `CLAUDE_OBSERVABILITY_LOG_PATH` resolves relative to the repo workspace root.
|
||||
- UI API: `GET /api/claude-trace?limit=<n>&sessionId=<id>` reads filtered Claude trace records.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
CLAUDE_OBSERVABILITY_MODE=both
|
||||
CLAUDE_OBSERVABILITY_VERBOSITY=summary
|
||||
CLAUDE_OBSERVABILITY_LOG_PATH=.ai_ops/events/claude-trace.ndjson
|
||||
CLAUDE_OBSERVABILITY_INCLUDE_PARTIAL=false
|
||||
CLAUDE_OBSERVABILITY_DEBUG=false
|
||||
```
|
||||
|
||||
### Analytics Quick Start
|
||||
|
||||
Inspect latest events:
|
||||
@@ -245,6 +276,7 @@ jq -c 'select(.severity=="critical")' .ai_ops/events/runtime-events.ndjson
|
||||
- Pipeline behavior on `SecurityViolationError` is configurable:
|
||||
- `hard_abort` (default)
|
||||
- `validation_fail` (retry-unrolled remediation)
|
||||
- `dangerous_warn_only` (logs violations and continues execution; high risk)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
@@ -259,6 +291,13 @@ jq -c 'select(.severity=="critical")' .ai_ops/events/runtime-events.ndjson
|
||||
- `ANTHROPIC_API_KEY` (used when `CLAUDE_CODE_OAUTH_TOKEN` is unset)
|
||||
- `CLAUDE_MODEL`
|
||||
- `CLAUDE_CODE_PATH`
|
||||
- `CLAUDE_MAX_TURNS` (integer >= 1, defaults to `2`)
|
||||
- `CLAUDE_OBSERVABILITY_MODE` (`off`, `stdout`, `file`, or `both`)
|
||||
- `CLAUDE_OBSERVABILITY_VERBOSITY` (`summary` or `full`)
|
||||
- `CLAUDE_OBSERVABILITY_LOG_PATH`
|
||||
- `CLAUDE_OBSERVABILITY_INCLUDE_PARTIAL` (`true` or `false`)
|
||||
- `CLAUDE_OBSERVABILITY_DEBUG` (`true` or `false`)
|
||||
- `CLAUDE_OBSERVABILITY_DEBUG_LOG_PATH`
|
||||
- `MCP_CONFIG_PATH`
|
||||
|
||||
### Agent Manager Limits
|
||||
@@ -274,6 +313,7 @@ jq -c 'select(.severity=="critical")' .ai_ops/events/runtime-events.ndjson
|
||||
- `AGENT_TOPOLOGY_MAX_DEPTH`
|
||||
- `AGENT_TOPOLOGY_MAX_RETRIES`
|
||||
- `AGENT_RELATIONSHIP_MAX_CHILDREN`
|
||||
- `AGENT_MERGE_CONFLICT_MAX_ATTEMPTS`
|
||||
|
||||
### Provisioning / Resource Controls
|
||||
|
||||
@@ -289,7 +329,7 @@ jq -c 'select(.severity=="critical")' .ai_ops/events/runtime-events.ndjson
|
||||
|
||||
### Security Middleware
|
||||
|
||||
- `AGENT_SECURITY_VIOLATION_MODE` (`hard_abort` or `validation_fail`)
|
||||
- `AGENT_SECURITY_VIOLATION_MODE` (`hard_abort`, `validation_fail`, or `dangerous_warn_only`)
|
||||
- `AGENT_SECURITY_ALLOWED_BINARIES`
|
||||
- `AGENT_SECURITY_COMMAND_TIMEOUT_MS`
|
||||
- `AGENT_SECURITY_AUDIT_LOG_PATH`
|
||||
|
||||
Reference in New Issue
Block a user