ccx-native 0.0.1 → 0.2.0

package/skills/ccx/references/troubleshooting.md

@@ -0,0 +1,94 @@
+# ccx troubleshooting
+
+## Delivery and steering
+
+`send` and `steer` have delivery ids (`--json`, or supply `--delivery-id`).
+Retry the same message with the same id to avoid duplicate delivery.
+`ccx reconcile TARGET --delivery-id ID` checks without sending; Codex also
+accepts `--turn-id`.
+
+If a `new` reply was lost, `ccx list` may find the worker. For retryable
+creation, choose a UUIDv4 first and reuse it with `--worker-id`; bare `new`
+always creates another worker.
+
+A Claude `steer` watches for where the message landed:
+
+| Status | Meaning |
+|---|---|
+| `consumed-current-turn` | the running turn took it |
+| `started-next-turn` | it runs as the next turn |
+| `accepted-pending` | ccx holds it; placement is unproven. Wait or reconcile; don't resend. |
+| `unknown` | reconcile before retrying |
+
+Pending Claude steering blocks other sends and steers; the refusal names its
+delivery id. Codex steering accepts or rejects at once.
+
+## Stopped, failed and revived workers
+
+Idle workers stop after `--idle-timeout`. Stopped or failed workers revive on
+`send`, keeping their history. Interrupted turns aren't resumed or resent:
+check `report`, then send what remains.
+
+`ccx resume TARGET` reloads without starting a turn. `ccx shutdown` stops
+runtimes, preserving histories; `--engine` limits it to one engine.
+
+## Workers waiting on background work
+
+A Claude worker can finish a turn while a background task or monitor keeps
+running, then wake for another turn. `peek` and `report` show background tasks.
+
+To follow finite work the worker is waiting on (tests or a build):
+
+- Claude or a person: `ccx wait TARGET --next-turn`
+- Codex: `ccx notify TARGET --next-turn`
+
+A server or watcher left running doesn't mean the work is unfinished.
+
+## Input requests
+
+`ccx peek TARGET` shows pending input and its request id.
+
+- **Question (Claude):** `ccx answer TARGET "Option label"`; see help for
+  multiple questions or selections.
+- **Permission:** `ccx approve TARGET` or `ccx reject TARGET`.
+- **MCP server form (Claude):** `ccx respond TARGET --accept --field
+  name=value`, `--decline` or `--cancel`.
+
+To follow the resumed turn, Claude/human parents add `--wait` where supported;
+Codex parents use `--notify-parent`.
+
+## Context and compaction
+
+Right after compaction, `ccx context TARGET --json` may show `tokens_used: null`
+until the next reading; `reason` explains why.
+
+Claude compaction revives stopped workers; Codex compaction needs an idle
+worker. `ccx notify TARGET` follows a compaction already running.
+
+`ccx set TARGET --model M --effort E` needs an idle or stopped worker. Codex
+uses the settings next turn. For a running, idle Claude worker, add `--restart`
+to stop its runtime; the next send revives it with the new settings. A stopped
+Claude worker uses them on revival. Let compaction settle before `set`.
+
+## Usage caps
+
+Caps stop a turn at the given account usage percentage (exit 7). Check
+`ccx usage` first. Caps apply only to that message; later sends need their own.
+If usage can't be read, the turn keeps running.
+
+## Deeper inspection
+
+- `ccx peek TARGET --full`: untruncated messages and tool errors.
+- `ccx logs TARGET --full`: conversation JSON without tool-result truncation,
+  including stopped workers. Claude's `--jsonl` gives the raw transcript.
+- `ccx events TARGET --follow`: lifecycle events for diagnostics.
+- `ccx import ID`: bring an idle Claude session into ccx, or fork a Codex
+  thread whose latest turn completed.
+
+## Engine differences
+
+- `answer`, `respond`, `--cap-opus`, `--next-turn` and `logs --jsonl` are
+  Claude-only. `--settle` (also wait for workers a Codex worker started) and
+  `reconcile --turn-id` are Codex-only.
+- Codex workers share one ccx-managed Codex daemon. `kill` unloads a single
+  worker and leaves the others running.

package/skills/ccx/references/variables.md

@@ -0,0 +1,62 @@
+# ccx variables
+
+Variables are named JSON values attached to a worker. Inside the worker,
+plain `python3` (or `python`) sees them as ordinary Python variables; changes
+are saved and visible to every worker sharing the same state.
+
+## Attach, update, read
+
+```bash
+W=$(ccx new --engine codex --cwd ~/repo --var 'result={"done": false, "issues": []}' \
+      "List the TODOs in src/. With python3, append each to result['issues'], then set result['done'] = True last.")
+ccx wait "$W"
+ccx vars "$W" result --json          # the value
+ccx vars "$W" --json                 # names and metadata only
+```
+
+- `--var NAME=JSON` works on `new`, `send` and `fork`, and is repeatable. On
+  `send` it attaches or replaces that variable.
+- ccx tells the worker which names are available; you don't need to explain
+  the mechanism, just say what to put where.
+- Inside the worker, mutating a value or rebinding the name both write back;
+  `del NAME` removes it.
+- Start with a sentinel (`done: false`) and ask the worker to set it last, so an
+  untouched value can't pass as an empty result.
+
+## Sharing between workers
+
+`--vars-from TARGET` gives a new worker (or a `send`) the same state as
+`TARGET`, across Claude and Codex. Both see each other's changes at once, and
+ccx runs their Python calls one at a time.
+
+```bash
+B=$(ccx new --engine claude --cwd ~/repo --vars-from "$W" \
+      "With python3, replace each string in result['issues'] with a dict: text holds the string, priority is high or low.")
+```
+
+`--var` and `--vars-from` can't be combined in one command. A `fork` doesn't
+copy the source's variables (pass `--vars-from SOURCE` to share them), and
+workers a worker starts never inherit its variables.
+
+## Rules
+
+- Variables need full permissions (the default).
+- Values attached from the CLI are JSON. A controller can attach live Python
+  objects instead; see [controllers.md](controllers.md).
+- Only direct `python`/`python3` sees them. `command python3`, `env python3`,
+  a full interpreter path and scripts run through a shebang get normal Python.
+  In Codex workers, nested bash and zsh keep them; in Claude workers, call
+  `python3` directly from the tool shell.
+- Keep values small and structured: verdicts, lists, paths, handles.
+
+## When python3 doesn't see them
+
+Check the worker's exact command and its selected Python with
+`command -v python3` and `command python3 --version`. Leading interpreter flags
+such as `python3 -u` bypass variables. On stock macOS, a non-login shell can
+find Apple's older `/usr/bin/python3`, which can't run them.
+
+Live controller objects require Python to match the controller's version and
+platform; otherwise ccx runs ordinary Python with a warning. Saved JSON has no
+matching-version check, but needs Python capable of running ccx's variable
+support. See [variable troubleshooting](https://github.com/ccx-native/ccx/blob/main/docs/variables/troubleshooting.md).