forked from cleveragents/cleveragents-core
Docs: Fixed some contradictions and ambiguity in the specification document
This commit is contained in:
+29
-17
@@ -89,7 +89,7 @@ The following standards are integrated into the architecture:
|
||||
: A persisted choice point in a plan's decision tree, created during Strategize or Execute. Records the question, chosen option, alternatives, confidence score, rationale, context snapshot, and downstream dependencies. Types: `prompt_definition`, `invariant_enforced`, `strategy_choice`, `subplan_spawn`, `subplan_parallel_spawn`, among others. Supports targeted correction with selective subtree recomputation.
|
||||
|
||||
Invariant
|
||||
: A natural-language constraint on plan execution scoped to global, project, action, or plan level. Precedence: ==plan > action > project > global==. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as `invariant_enforced` decisions that propagate to child plans.
|
||||
: A natural-language constraint on plan execution scoped to global, project, action, or plan level. Action invariants are promoted to plan-level when the action is used, so the runtime precedence chain is three-tier: ==plan > project > global==. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as `invariant_enforced` decisions that propagate to child plans.
|
||||
|
||||
Automation Profile
|
||||
: A named set of confidence thresholds (each `0.0`–`1.0`) gating which plan operations proceed automatically versus requiring human approval. `0.0` = always automatic; `1.0` = always manual. Eight built-in profiles (`manual` through `full-auto`). Custom profiles namespaced as `[[server:]namespace/]name`.
|
||||
@@ -115,7 +115,7 @@ The following standards are integrated into the architecture:
|
||||
: The association between a tool and the resources it operates on, declared via typed resource slots. Slots resolve through **contextual binding** (from the plan's project), **static binding** (hardcoded at registration), or **parameter binding** (passed at invocation).
|
||||
|
||||
Resource Registry
|
||||
: The persistent catalog of all registered resources and their DAG relationships (parent/child links). One of the core registries, alongside the Tool Registry, Skill Registry, Actor Registry, and Provider Registry.
|
||||
: The persistent catalog of all registered resources and their DAG relationships (parent/child links). One of the core registries, alongside the Tool Registry, Skill Registry, Actor Registry, Provider Registry, and LSP Registry.
|
||||
|
||||
???+ abstract "Tools & Skills"
|
||||
|
||||
@@ -3185,7 +3185,7 @@ Show full project details.
|
||||
│ <span style="opacity: 0.7;">resource: local/api-repo scope: project (attachment: 01HXM5A1B2C3D4E5F6G7…)</span>│
|
||||
│ <span style="color: cyan; font-weight: 600;">local/lint-check</span> Lint check <span style="color: #66cc66; font-weight: 600;">required</span> │
|
||||
│ <span style="opacity: 0.7;">resource: local/api-repo scope: direct (always active) (attachment: 01HXM5…)</span>│
|
||||
│ <span style="color: cyan; font-weight: 600;">local/check-bundle-size</span> Check bundle size (advisory) <span style="color: yellow; font-weight: 600;">info</span> │
|
||||
│ <span style="color: cyan; font-weight: 600;">local/check-bundle-size</span> Check bundle size (advisory) <span style="color: yellow; font-weight: 600;">informational</span> │
|
||||
│ <span style="opacity: 0.7;">resource: local/api-repo scope: project (attachment: 01HXM5D4E5F6G7H8J9…)</span>│
|
||||
╰───────────────────────────────────────────────────────────────────────────────────╯
|
||||
|
||||
@@ -3235,7 +3235,7 @@ Show full project details.
|
||||
resource: local/api-repo scope: project (attachment: 01HXM5A1B2C3D4E5F6G7...)
|
||||
local/lint-check Lint check required
|
||||
resource: local/api-repo scope: direct (always active) (attachment: 01HXM5...)
|
||||
local/check-bundle-size Check bundle size (advisory) info
|
||||
local/check-bundle-size Check bundle size (advisory) informational
|
||||
resource: local/api-repo scope: project (attachment: 01HXM5D4E5F6G7H8J9...)
|
||||
|
||||
Context
|
||||
@@ -16419,11 +16419,11 @@ Archive an action.
|
||||
| Profile | Description |
|
||||
| :------ | :---------- |
|
||||
| `manual` | All thresholds at `1.0` — everything requires approval |
|
||||
| `review` | Automatic strategize, manual execute and apply |
|
||||
| `supervised` | Automatic strategize and execute, manual apply |
|
||||
| `review` | Automatic strategize and execute, manual apply |
|
||||
| `supervised` | Automatic strategize, manual execute and apply |
|
||||
| `cautious` | Most operations automatic, manual for risky decisions |
|
||||
| `trusted` | Nearly fully automatic, manual only for apply |
|
||||
| `auto` | Fully automatic except strategy revisions |
|
||||
| `auto` | Fully automatic except apply |
|
||||
| `ci` | Optimized for CI/CD pipelines |
|
||||
| `full-auto` | All thresholds at `0.0` — fully autonomous |
|
||||
|
||||
@@ -16463,6 +16463,7 @@ Register a new custom automation profile from a YAML configuration file. The pro
|
||||
│ <span style="color: #66cc66; font-weight: 600;">auto_decisions_execute:</span> 0.0 │
|
||||
│ <span style="color: #66cc66; font-weight: 600;">auto_validation_fix:</span> 0.0 │
|
||||
│ <span style="color: #ff6666; font-weight: 600;">auto_strategy_revision:</span> 1.0 │
|
||||
│ <span style="color: #ff6666; font-weight: 600;">auto_reversion_from_apply:</span> 1.0 │
|
||||
│ <span style="color: #66cc66; font-weight: 600;">auto_child_plans:</span> 0.0 │
|
||||
│ <span style="color: #66cc66; font-weight: 600;">auto_retry_transient:</span> 0.0 │
|
||||
│ <span style="color: #66cc66; font-weight: 600;">auto_checkpoint_restore:</span> 0.0 │
|
||||
@@ -16492,6 +16493,7 @@ Register a new custom automation profile from a YAML configuration file. The pro
|
||||
auto_decisions_execute: 0.0
|
||||
auto_validation_fix: 0.0
|
||||
auto_strategy_revision: 1.0
|
||||
auto_reversion_from_apply: 1.0
|
||||
auto_child_plans: 0.0
|
||||
auto_retry_transient: 0.0
|
||||
auto_checkpoint_restore: 0.0
|
||||
@@ -16521,6 +16523,7 @@ Register a new custom automation profile from a YAML configuration file. The pro
|
||||
"auto_decisions_execute": 0.0,
|
||||
"auto_validation_fix": 0.0,
|
||||
"auto_strategy_revision": 1.0,
|
||||
"auto_reversion_from_apply": 1.0,
|
||||
"auto_child_plans": 0.0,
|
||||
"auto_retry_transient": 0.0,
|
||||
"auto_checkpoint_restore": 0.0
|
||||
@@ -16554,6 +16557,7 @@ Register a new custom automation profile from a YAML configuration file. The pro
|
||||
auto_decisions_execute: 0.0
|
||||
auto_validation_fix: 0.0
|
||||
auto_strategy_revision: 1.0
|
||||
auto_reversion_from_apply: 1.0
|
||||
auto_child_plans: 0.0
|
||||
auto_retry_transient: 0.0
|
||||
auto_checkpoint_restore: 0.0
|
||||
@@ -17993,9 +17997,9 @@ Every plan should have:
|
||||
|
||||
| Field | Type | Description |
|
||||
| :---- | :--- | :---------- |
|
||||
| `plan_id` | UUID/ULID | ==Unique, immutable== identifier |
|
||||
| `parent_plan_id` | UUID/ULID? | Nullable; present for child plans |
|
||||
| `root_plan_id` | UUID/ULID | The top-most plan in the tree |
|
||||
| `plan_id` | ULID | ==Unique, immutable== identifier |
|
||||
| `parent_plan_id` | ULID? | Nullable; present for child plans |
|
||||
| `root_plan_id` | ULID | The top-most plan in the tree |
|
||||
| `attempt` | Integer | Attempt counter (increments on phase re-run) |
|
||||
| `created_at` | Timestamp | When the plan was created |
|
||||
| `updated_at` | Timestamp | Last modification time |
|
||||
@@ -24140,11 +24144,17 @@ The Resource Registry persists in the database (local SQLite or server). It work
|
||||
|--------------|------------------|-------------------|
|
||||
| `git-checkout` | `git_worktree` | Git reset/checkout |
|
||||
| `git` | `none` | N/A (represents a repo instance — not directly sandboxable) |
|
||||
| `fs-mount` | `copy_on_write` or `overlay` | Restore from snapshot |
|
||||
| `fs-directory` | `copy_on_write` | Restore from snapshot |
|
||||
| `fs-mount` | `copy_on_write`, `filesystem_copy`, or `overlay` | Restore from snapshot or delete copy |
|
||||
| `fs-directory` | `copy_on_write` or `filesystem_copy` | Restore from snapshot or delete copy |
|
||||
| Custom database types | `transaction_rollback` | Transaction rollback |
|
||||
| Custom API types | `none` (often not sandboxable) | N/A |
|
||||
|
||||
**Filesystem sandbox strategies** differ in their prerequisites and tradeoffs:
|
||||
|
||||
- **`copy_on_write`**: Leverages the filesystem's native copy-on-write capability (e.g., BTRFS, ZFS). The filesystem preserves original data blocks when edits occur, creating lightweight snapshots without duplicating data upfront. Only available on CoW-capable filesystems.
|
||||
- **`filesystem_copy`**: Performs an explicit full copy of the resource directory (e.g., via `cp`). Works on all writable filesystems regardless of CoW support, at the cost of duplicating data upfront.
|
||||
- **`overlay`**: Uses an overlay filesystem (e.g., OverlayFS) to layer changes on top of the original directory. Writes go to the upper layer while the lower layer remains untouched. Requires OS-level overlay mount support.
|
||||
|
||||
The sandbox strategy is inherited by child resources from their parent unless the child type defines its own. For example, `git-branch`, `git-commit`, `git-tree`, and `git-tree-entry` all inherit from their `git` ancestor. `fs-file`, `fs-symlink`, and `fs-hardlink` inherit from their `fs-directory` parent.
|
||||
|
||||
#### Lazy Sandboxing
|
||||
@@ -25833,7 +25843,7 @@ Linked Resources
|
||||
Validations (3)
|
||||
local/run-tests pytest <span style="color: cyan;">--cov</span>=src <span style="color: cyan;">--cov-fail-under</span>=80 required
|
||||
local/lint-check ruff check . required
|
||||
local/check-bundle-size node scripts/check-bundle-size.js info
|
||||
local/check-bundle-size node scripts/check-bundle-size.js informational
|
||||
|
||||
Context
|
||||
Include: repo
|
||||
@@ -25984,7 +25994,7 @@ Summary
|
||||
╭─ Validations (3) ────────────────────────────────────────────────────╮
|
||||
│ <span style="color: cyan; font-weight: 600;">local/run-tests</span> pytest <span style="color: cyan;">--cov</span>=src <span style="color: cyan;">--cov-fail-under</span>=80 <span style="color: #66cc66; font-weight: 600;">required</span> │
|
||||
│ <span style="color: cyan; font-weight: 600;">local/lint-check</span> ruff check . <span style="color: #66cc66; font-weight: 600;">required</span> │
|
||||
│ <span style="color: cyan; font-weight: 600;">local/check-bundle-size</span> node scripts/check-bundle-size.js <span style="color: yellow; font-weight: 600;">info</span> │
|
||||
│ <span style="color: cyan; font-weight: 600;">local/check-bundle-size</span> node scripts/check-bundle-size.js <span style="color: yellow; font-weight: 600;">informational</span> │
|
||||
╰──────────────────────────────────────────────────────────────────────╯
|
||||
|
||||
╭─ Context ───────────────────╮
|
||||
@@ -27457,7 +27467,7 @@ The three safety flags (`require_sandbox`, `require_checkpoints`, `allow_unsafe_
|
||||
|
||||
| Flag | Type | Description | Behavior |
|
||||
|------|------|-------------|----------|
|
||||
| `auto_strategize` | float (0.0–1.0) | Automatically enter Strategize after `plan use` | When confidence >= threshold, Strategize begins immediately. Below threshold, system pauses; user must run `agents plan execute` to start Strategize. |
|
||||
| `auto_strategize` | float (0.0–1.0) | Automatically enter Strategize after `plan use` | When confidence >= threshold, Strategize begins immediately. Below threshold, system pauses after plan creation for user confirmation before entering Strategize. |
|
||||
| `auto_execute` | float (0.0–1.0) | Automatically proceed from Strategize to Execute | When confidence >= threshold, Execute begins when Strategize completes. Below threshold, system pauses for user review. |
|
||||
| `auto_apply` | float (0.0–1.0) | Automatically proceed from Execute to Apply | When confidence >= threshold, Apply begins when Execute completes. Below threshold, system pauses for user diff review. |
|
||||
| `auto_decisions_strategize` | float (0.0–1.0) | Automatically make decisions during Strategize | When confidence >= threshold, the strategy actor makes the decision autonomously. Below threshold, system pauses at the decision point for user input. |
|
||||
@@ -40052,7 +40062,7 @@ Every ACP operation routes to a specific Application-layer service method. The f
|
||||
| `{entity}.update` | `PUT /api/v1/{entities}/{name}` | `{Entity}Service.update()` |
|
||||
| `{entity}.remove` | `DELETE /api/v1/{entities}/{name}` | `{Entity}Service.remove()` |
|
||||
|
||||
Where `{entity}` is one of: `actor`, `skill`, `tool`, `validation`, `resource`, `resource_type`, `project`, `action`, `automation_profile`, `invariant`.
|
||||
Where `{entity}` is one of: `actor`, `skill`, `tool`, `validation`, `resource`, `resource_type`, `project`, `action`, `automation_profile`, `invariant`, `lsp`.
|
||||
|
||||
**Context Operations**
|
||||
|
||||
@@ -42552,7 +42562,9 @@ The sandbox is the primary safety mechanism preventing untested changes from rea
|
||||
| Strategy | Isolation Level | Resource Type | Mechanism | Rollback |
|
||||
|---|---|---|---|---|
|
||||
| `git_worktree` | Process-level filesystem isolation | Git repositories | Creates a separate git worktree on a plan-specific branch. Changes are confined to the worktree directory. Merge back to main requires explicit apply. | `git checkout -- .` or worktree deletion |
|
||||
| `filesystem_copy` | Process-level filesystem isolation | Non-git filesystems | Creates a copy-on-write snapshot (using `cp --reflink=auto` where supported, falling back to full copy). Original files are never modified during execution. | Delete the copy directory |
|
||||
| `copy_on_write` | Process-level filesystem isolation | Filesystems with native CoW support (e.g., BTRFS, ZFS) | Leverages the filesystem's native copy-on-write capability to create a lightweight snapshot. The filesystem preserves original blocks when edits occur, requiring no explicit copy. Only available on CoW-capable filesystems. | Restore from snapshot |
|
||||
| `filesystem_copy` | Process-level filesystem isolation | All writable filesystems | Creates an explicit full copy of the resource directory (using `cp` or equivalent). Works on any writable filesystem regardless of CoW support, at the cost of duplicating data upfront. Original files are never modified during execution. | Delete the copy directory |
|
||||
| `overlay` | Process-level filesystem isolation | Filesystems supporting overlay mounts | Uses an overlay filesystem (e.g., OverlayFS) to layer changes on top of the original. Writes go to the upper layer; the lower layer remains untouched. | Remove the overlay mount |
|
||||
| `transaction_rollback` | Database transaction isolation | Databases | Opens a database transaction with `SERIALIZABLE` isolation level. All changes are staged within the transaction. Commit on apply; rollback on cancel/error. | `ROLLBACK` |
|
||||
| `none` | No isolation | Any | Changes are applied directly. Requires `require_sandbox: false` in the automation profile. Only appropriate when external safety mechanisms exist. | No automatic rollback |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user