Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -414,6 +414,7 @@ evidence → recovery; continuation → governance.
| --- | --- | --- |
| Goal state and status | Tracks active state, todos, claims, gates, evidence, run history, and first-screen attention. | `loopx status`, `loopx diagnose`, `loopx review-packet` |
| Quota and interaction contract | Decides whether a turn should deliver, ask, wait, self-repair, or stay quiet. | `loopx quota should-run`, [quota allocation](docs/quota-allocation.md) |
| Company control loop | Routes company work to AI, human decisions, human execution, monitors, or blockers; reconciles evidence into the next planning cycle. | `loopx company-control-loop`, [company control loop](docs/reference/company-control-loop.md) |
| Agent runtime bridges | Keeps Codex App, Codex CLI, Claude Code, and generic workers aligned with the same guard. | `loopx heartbeat-prompt`, `loopx codex-cli-bootstrap-message`, `loopx worker-bridge` |
| Operator surfaces | Renders compact status without making the browser the state authority. | `loopx serve-status`, [dashboard](apps/presentation/dashboard/README.md) |
| Session dash | Starts a live single-page panel that tracks fleet progress: sessions, their goals, and each goal's status/todo progress, with result statistics; auto-refreshes in place. | `loopx dash`, [session dash design](docs/product/surfaces/session-dash-panel-design.md) |
Expand Down
1 change: 1 addition & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -370,6 +370,7 @@ Kernel 把控制面归结为五个用户可以直接行动的问题。每个问
| --- | --- | --- |
| Goal state 与 status | 跟踪 active state、todo、claim、gate、evidence、run history 和首屏关注点。 | `loopx status`、`loopx diagnose`、`loopx review-packet` |
| Quota 与 interaction contract | 决定一轮应该执行、提问、等待、自修复还是静默。 | `loopx quota should-run`、[Quota Allocation](docs/quota-allocation.md) |
| Company Control Loop | 将公司工作路由给 AI、人类决策、人类执行、监控或 blocker,并把证据汇入下一轮规划。 | `loopx company-control-loop`、[Company Control Loop](docs/reference/company-control-loop.md) |
| Agent runtime bridge | 让 Codex App、Codex CLI、Claude Code 和 generic worker 服从同一 guard。 | `loopx heartbeat-prompt`、`loopx codex-cli-bootstrap-message`、`loopx worker-bridge` |
| Operator surface | 呈现紧凑状态,但不让浏览器成为状态事实源。 | `loopx serve-status`、[Dashboard](apps/presentation/dashboard/README.md) |
| External projection | 把 todo / gate 投影到协作表面,同时保持 LoopX 权威。 | `loopx lark-kanban`、[Lark Kanban adapter](docs/integrations/lark-kanban-control-plane-adapter.md) |
Expand Down
1 change: 1 addition & 0 deletions docs/architecture/rfcs/loopx-overall-roadmap-v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ These directly determine whether a long-running team is usable. A directory or R
| Area and existing entry | Streams | Next requirement in this roadmap |
| --- | --- | --- |
| [Goal Vision/replan](../../reference/protocols/goal-vision-replan-contract-v0.md), [work graph](../../reference/protocols/task-graph-projection-v0.md), [peer runtime](../../reference/protocols/peer-agent-runtime-v1.md), [supervisor](../../reference/protocols/peer-supervisor-v0.md) | S2/S3 | Exercise dependencies, replanning, acceptance and handoff in one real case; aggregate closeout consumes acceptance facts |
| [Company control-loop profile](../../reference/company-control-loop.md) | S1/S3 | Keep it a bounded caller of Goal/Todo/evidence owners; qualify the broader steward claim only through R2/R3 multi-Agent adoption, dependent artifacts, independent acceptance, recovery and result return |
| [Quota](../../quota-allocation.md), [cadence](../../operations/long-task-cadence-policy.md), [attention](../../operations/attention-queue.md) | S5/S7 | Budget exhaustion, deferral and blocking expose next triggers/readback; scale without frequent full-state polling |
| [Material lifecycle](../../reference/protocols/material-lifecycle-architecture-v0.md), [material frontier](../../reference/protocols/agent-material-frontier-v0.md), [authority registration](../../operations/authority-source-registration.md) | S6 | Agents discover roadmap/RFC revisions and record reads; reading grants neither agreement nor authority; archival preserves raw-source ownership |
| [Decision Context](../../../loopx/capabilities/decision_context/README.md), [Reward Memory](../../../loopx/capabilities/reward_memory/README.md), [Semantic Preference](../../../loopx/capabilities/semantic_preference/README.md), [Turn Recall](../../../loopx/capabilities/agent_turn_recall/README.md) | S6/S11 | Distinguish facts/preferences/advice/attribution/authority; scoped recall, expiry and outcome-feedback counterexamples first |
Expand Down
1 change: 1 addition & 0 deletions docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ LoopX 的目标是让人用本地前端或 Lark 提出、修订和验收复杂
| 领域与已有入口 | 所属工作流 | 当前总纲要求的下一步 |
| --- | --- | --- |
| [Goal Vision/replan](../../reference/protocols/goal-vision-replan-contract-v0.md)、[work graph](../../reference/protocols/task-graph-projection-v0.md)、[peer runtime](../../reference/protocols/peer-agent-runtime-v1.md)、[监督](../../reference/protocols/peer-supervisor-v0.md) | S2/S3 | 将跨工作依赖、重规划、验收与 handoff 放进同一个真实案例;aggregate closeout 必须消费验收事实 |
| [公司控制闭环 profile](../../reference/company-control-loop.md) | S1/S3 | 保持为 Goal/Todo/证据 owner 的有界 caller;更广的 steward 主张必须通过 R2/R3 的多 Agent adoption、依赖产物、独立验收、恢复和结果返回来验收 |
| [quota](../../quota-allocation.md)、[cadence](../../operations/long-task-cadence-policy.md)、[attention](../../operations/attention-queue.md) | S5/S7 | 预算耗尽/延期/被阻塞时有明确下一次触发及用户回读;百 Agent 不靠高频全文轮询 |
| [材料生命周期](../../reference/protocols/material-lifecycle-architecture-v0.zh-CN.md)、[材料 frontier](../../reference/protocols/agent-material-frontier-v0.md)、[authority 注册](../../operations/authority-source-registration.md) | S6 | 路线/RFC 更新能由 Agent 按 revision 发现并登记阅读;read receipt 不表示同意或获得权限;归档不丢原始来源 |
| [Decision Context](../../../loopx/capabilities/decision_context/README.md)、[Reward Memory](../../../loopx/capabilities/reward_memory/README.md)、[Semantic Preference](../../../loopx/capabilities/semantic_preference/README.md)、[Turn Recall](../../../loopx/capabilities/agent_turn_recall/README.md) | S6/S11 | 区分事实、偏好、建议、归因和权威;同一 scope 的回忆/失效/结果反馈负例先行 |
Expand Down
121 changes: 121 additions & 0 deletions docs/reference/company-control-loop.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# Company Control Loop

The Company Control Loop is LoopX's provider-neutral planning layer for a
long-running company direction. It routes bounded work to AI or people, keeps
the result under one Goal, reconciles Todo evidence, and produces the next
planning cycle.

## Roadmap placement

This command is a bounded planning profile for the persistent steward path in
the [LoopX overall roadmap](../architecture/rfcs/loopx-overall-roadmap-v0.md),
primarily S1 and S3. It exercises existing Goal, Todo, evidence, quota, and
replan owners; it does not create a second steward, work ledger, scheduler, or
authority model. Its current acceptance boundary is the documented CLI and
packaged runtime lifecycle. The broader R2/R3 journey still requires real
multi-Agent adoption, dependent artifacts, independent acceptance, restart
recovery, and automatic result return through their existing owners.

## Authority boundary

The command does not grant execution authority. Existing LoopX Todo rules own
claims, user gates, leases, validation, and completion. The company layer owns
only these decisions:

- `ai_execute` becomes an agent advancement Todo.
- `human_decide` becomes a blocking user gate.
- `human_execute` becomes a user action.
- `observe` becomes a bounded continuous monitor.
- prohibited work becomes a blocker.

A Todo marked done is accepted only when reconciliation also receives an
evidence reference. Completion without evidence becomes `awaiting_evidence`;
a blocked Todo becomes `replanning`.

## State lifecycle

Start with a `outcome_routing_plan_request_v0` JSON object. It contains one
direction, a cycle number, outcomes, work items, and feedback.

`company-control-loop` is the product profile. Its control-plane contracts,
effect IDs, state directory, and schemas use the domain-neutral
`outcome_routing_*` family so the shared work-item kernel does not acquire
company-specific vocabulary.

```sh
loopx company-control-loop project --state-json company.json
loopx company-control-loop save \
--goal-id company-goal \
--state-json company.json
```

Both commands are read-only at this point. Add `--execute` to `save` after
review. Replacing existing state also requires the exact revision returned by
`show` or the prior write:

```sh
loopx company-control-loop save \
--goal-id company-goal \
--state-json company.json \
--expected-revision REVISION \
--execute

loopx company-control-loop show --goal-id company-goal
```

## Materialize work as Todos

Preview the idempotent plan first, then execute it:

```sh
loopx company-control-loop sync-todos \
--goal-id company-goal \
--agent-id company-ceo \
--project /path/to/project

loopx company-control-loop sync-todos \
--goal-id company-goal \
--agent-id company-ceo \
--project /path/to/project \
--execute
```

The profile persists a revisioned `work_item_id` to `todo_id` binding after
Todo readback. Agent Todos may still use the kernel's existing `target_key`
identity. Human Todos remain ordinary `user_gate` and `user_action` records;
their correlation identity stays inside profile state. Failed readback or a
stale state revision stops the command.

## Reconcile and plan the next cycle

Reconciliation is also dry-run by default:

```sh
loopx company-control-loop reconcile-todos \
--goal-id company-goal \
--agent-id company-ceo \
--project /path/to/project

loopx company-control-loop reconcile-todos \
--goal-id company-goal \
--agent-id company-ceo \
--project /path/to/project \
--execute

loopx company-control-loop next-cycle --goal-id company-goal
```

`next-cycle` returns a new request object. Evidence-backed completed work leaves
the active frontier. Failures and missing evidence become typed feedback and
set `replan_required`. When no work remains, `goal_converged` is true.

Review the returned state before saving it as the next cycle. Revision checks
prevent an older planner or restarted worker from overwriting newer state.

## Always-on operation

An always-on host should run the ordinary LoopX heartbeat contract. Each wake
must enter through `quota should-run`, advance only the selected Todo, validate
the result, write state, and spend the matching slot. Scheduler cadence and
human notification remain host responsibilities; this command does not create
an independent hidden scheduler.
26 changes: 26 additions & 0 deletions loopx/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,15 @@

import argparse
import sys
from pathlib import Path

from .cli_commands.agent_capabilities import register_agent_capabilities, handle_agent_capabilities
from .cli_commands.agent_directory import register_agent_directory, handle_agent_directory
from .cli_commands.agent_context import register_agent_context, handle_agent_context
from .cli_commands.company_control_loop import (
handle_company_control_loop_command,
register_company_control_loop_command,
)
from .cli_commands.todo_continuation import register_todo_continuation, handle_todo_continuation
from .cli_commands.manager_inbox import register_manager_inbox, handle_manager_inbox
from .capabilities.content_ops.cli import (
Expand Down Expand Up @@ -330,6 +335,7 @@ def build_parser() -> LoopXArgumentParser:
register_manager_inbox(sub, add_subcommand_format)
register_agent_capabilities(sub, add_subcommand_format)
register_agent_context(sub, add_subcommand_format)
register_company_control_loop_command(sub, add_subcommand_format)
register_agent_directory(sub, add_subcommand_format)
register_lark_inbox_commands(sub, add_subcommand_format)
register_lark_kanban_commands(sub, add_subcommand_format)
Expand Down Expand Up @@ -770,6 +776,26 @@ def main(argv: list[str] | None = None) -> int:
if args.command == "agent-context":
return handle_agent_context(args, registry_path, print_payload, output_format)

company_control_loop_result = handle_company_control_loop_command(
args,
output_format=output_format,
print_payload=print_payload,
runtime_root=(
(
Path(args.runtime_root).expanduser().resolve()
if args.runtime_root
else effective_runtime_root(registry_path, None)
)
if args.command == "company-control-loop"
and args.company_control_loop_command
in {"save", "show", "sync-todos", "reconcile-todos", "next-cycle"}
else None
),
registry_path=registry_path,
)
if company_control_loop_result is not None:
return company_control_loop_result

if args.command == "agent-directory":
return handle_agent_directory(
args, registry_path, effective_runtime_root(registry_path, args.runtime_root),
Expand Down
Loading