toolang 0.2.2__tar.gz → 0.2.4__tar.gz

{toolang-0.2.2 → toolang-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolang
-Version: 0.2.2
+Version: 0.2.4
 Summary: A programming language and runtime for agents
 Project-URL: Homepage, https://toolang.ai/
 Project-URL: Documentation, https://toolang.ai/docs

{toolang-0.2.2 → toolang-0.2.4}/docs/api.md

@@ -18,8 +18,14 @@ Top-level commands are:
 - `remove`
 - `list`
 - `info`
+- `chat`
+- `steer`
+- `cancel`
+- `rewind`
+- `fork`
+- `threads`
+- `runs`
 - `model`
-- `plugin`
 - `run`
 - `start`
 - `stop`
@@ -83,8 +89,16 @@ toolang clone brice/alice
 toolang start alice
 toolang stop alice
 toolang info alice
+toolang alice chat "What changed today?"
+toolang alice chat --thread tui_3nprht9x "Continue"
+toolang alice chat --thread tui_3nprht9x --tui
+toolang alice threads
+toolang alice runs --thread tui_3nprht9x
+toolang alice steer run_ppkp9e94 "Use the smaller patch"
+toolang alice cancel tui_3nprht9x
+toolang alice rewind run_ppkp9e94 "Try again from here"
+toolang alice fork run_ppkp9e94 "Explore a different approach"
 toolang model list
-toolang plugin list
 ```
 
 
@@ -409,6 +423,12 @@ For multipart payload details:
 `POST /api/v1/chat/stream` returns one SSE stream that follows an AI SDK UI
 message stream subset.
 
+The CLI command for chat-style input is `toolang <agent> chat [message]`.
+Without `--thread`, the CLI creates a terminal chat thread. With `--thread`, it
+continues or opens that thread. Job thread ids are inspectable and controllable
+through thread and run commands, but `chat` does not implicitly reopen tasks or
+create manual chore runs.
+
 
 ## Job Endpoints
 
@@ -417,23 +437,30 @@ message stream subset.
 - `PATCH /api/v1/jobs/{job_id}`
 - `GET /api/v1/jobs/archived`
 - `GET /api/v1/jobs/archived/{job_id}`
-- `PATCH /api/v1/jobs/archived/{job_id}`
 - `DELETE /api/v1/jobs/archived/{job_id}`
 - `GET /api/v1/tasks`
 - `POST /api/v1/tasks`
 - `GET /api/v1/tasks/{task_id}`
 - `PATCH /api/v1/tasks/{task_id}`
+- `POST /api/v1/tasks/{task_id}/draft`
+- `POST /api/v1/tasks/{task_id}/ready`
+- `POST /api/v1/tasks/{task_id}/archive`
+- `POST /api/v1/tasks/{task_id}/reopen`
+- `POST /api/v1/tasks/{task_id}/cancel`
 - `GET /api/v1/tasks/archived`
 - `GET /api/v1/tasks/archived/{task_id}`
-- `PATCH /api/v1/tasks/archived/{task_id}`
 - `DELETE /api/v1/tasks/archived/{task_id}`
 - `GET /api/v1/chores`
 - `POST /api/v1/chores`
 - `GET /api/v1/chores/{chore_id}`
 - `PATCH /api/v1/chores/{chore_id}`
+- `POST /api/v1/chores/{chore_id}/draft`
+- `POST /api/v1/chores/{chore_id}/ready`
+- `POST /api/v1/chores/{chore_id}/archive`
+- `POST /api/v1/chores/{chore_id}/run`
+- `POST /api/v1/chores/{chore_id}/cancel`
 - `GET /api/v1/chores/archived`
 - `GET /api/v1/chores/archived/{chore_id}`
-- `PATCH /api/v1/chores/archived/{chore_id}`
 - `DELETE /api/v1/chores/archived/{chore_id}`
 - `GET /api/v1/will`
 
@@ -442,14 +469,14 @@ message stream subset.
 `GET /api/v1/chores` return the same projections split by kind.
 
 List endpoints return authored job fields at the top level and runtime-derived
-state under `runtime`.
+status under `runtime`.
 
 Task items include:
 
 - `id`
 - `kind`
-- `state`
-- `stage`
+- `lifecycle`
+- `status`
 - `title`
 - `path`
 - `updated_at`
@@ -459,38 +486,45 @@ Chore items include:
 
 - `id`
 - `kind`
-- `state`
+- `lifecycle`
+- `status`
 - `schedule`
 - `title`
 - `path`
 - `updated_at`
 - `runtime`
 
-`state` values are:
+`lifecycle` values are:
 
-- `active`
-- `inactive`
+- `ready`
+- `draft`
 - `archived`
 
-Task `stage` values are:
+Task status values are:
 
 - `todo`
 - `running`
 - `done`
 - `failed`
+- `canceled`
+
+Chore status values are:
+
+- `todo`
+- `running`
+- `done`
 
 `runtime` contains:
 
 - `thread_id`
-- `active_run`
 - `last_run`
 - `next_run`
 
-`active_run` is the currently running run object or `null`. `last_run` is the
-most recent finished run object or `null`; it must not point at the same run as
-`active_run`. `next_run` is the next scheduled chore run or `null`.
+`last_run` is the latest run object or `null`. If `last_run.status` is
+`running`, that run is the active run. `next_run` is the next scheduled chore
+run or `null`.
 
-Default job list endpoints return active and inactive jobs. Archived jobs are
+Default job list endpoints return ready jobs. Draft and archived jobs are
 available only through explicit `/archived` routes.
 
 Detail endpoints return the same item shape plus `body`.
@@ -500,17 +534,13 @@ Task create requests accept:
 ```json
 {
   "title": "Review API changes",
-  "body": "Review the API changes and summarize risks.",
-  "state": "active",
-  "stage": "todo"
+  "body": "Review the API changes and summarize risks."
 }
 ```
 
-Task patch requests accept any subset of `title`, `body`, `state`, and `stage`.
-Patch `state: "inactive"` on the normal route to pause a task, and patch
-`state: "active"` on the normal route to resume it. Patch `state: "archived"`
-on the normal route to archive a task. Patch `state: "active"` or
-`state: "inactive"` on the archived route to unarchive it.
+Task patch requests accept any subset of `title` and `body`. Lifecycle actions
+use the task `draft`, `ready`, and `archive` endpoints. `task reopen` sets a
+completed, failed, or canceled task back to scheduler status `todo`.
 Delete is destructive and is available only through archived routes.
 
 Chore create requests accept:
@@ -519,16 +549,13 @@ Chore create requests accept:
 {
   "title": "Check stale PRs",
   "body": "Check stale pull requests and summarize blockers.",
-  "state": "active",
   "schedule": "FREQ=HOURLY;INTERVAL=6"
 }
 ```
 
-Chore patch requests accept any subset of `title`, `body`, `state`, and
-`schedule`. Patch `state: "inactive"` on the normal route to pause a chore,
-and patch `state: "active"` on the normal route to resume it. Patch
-`state: "archived"` on the normal route to archive a chore. Patch
-`state: "active"` or `state: "inactive"` on the archived route to unarchive it.
+Chore patch requests accept any subset of `title`, `body`, and `schedule`.
+Lifecycle actions use the chore `draft`, `ready`, and `archive` endpoints.
+`chore run` starts one manual occurrence without changing the schedule.
 Delete is destructive and is available only through archived routes.
 
 
@@ -537,7 +564,9 @@ Delete is destructive and is available only through archived routes.
 - `GET /api/v1/runs`
 - `GET /api/v1/runs/{run_id}`
 - `POST /api/v1/runs/{run_id}/steer`
-- `POST /api/v1/runs/{run_id}/stop`
+- `POST /api/v1/runs/{run_id}/cancel`
+- `POST /api/v1/runs/{run_id}/rewind`
+- `POST /api/v1/runs/{run_id}/fork`
 - `GET /api/v1/instruct/{hash}`
 - `GET /api/v1/context/{hash}`
 - `GET /api/v1/threads`
@@ -547,6 +576,10 @@ Delete is destructive and is available only through archived routes.
 
 `/api/v1/runs/{run_id}` is the main trace-detail endpoint.
 
+`steer` and `cancel` operate on running runs. `rewind` and `fork` operate on
+branchable chat threads by taking a run id as the anchor; task and chore threads
+cannot be rewound or forked because their thread ids are derived from job ids.
+
 
 ## Hook Endpoints
 

{toolang-0.2.2 → toolang-0.2.4}/docs/chat.md

@@ -25,9 +25,8 @@ Thread ids use one underscore-delimited normalized form:
 
 Examples:
 
-- `task_3nprht9x`
-- `chore_xy1234ab`
-- `chat_ab12cd34`
+- `tsk_3nprht9x`
+- `chr_xy1234ab`
 - `web_def456gh`
 - `tui_jk789mnp`
 - `tg_123456789`
@@ -112,6 +111,10 @@ To build a full transcript, flatten:
 1. each run input
 2. each step message in run order
 
+Forked chat threads store their source thread and anchor run in `parent`.
+Inherited transcript context includes visible source-thread runs before the
+anchor run.
+
 
 ## Run API
 
@@ -124,6 +127,27 @@ Run detail returns:
 `output.steps` contains the projected step detail for the run. This is the
 source used by trace and chat inspection pages.
 
+Run control endpoints are:
+
+- `POST /api/v1/runs/{run_id}/steer`
+- `POST /api/v1/runs/{run_id}/cancel`
+- `POST /api/v1/runs/{run_id}/rewind`
+- `POST /api/v1/runs/{run_id}/fork`
+
+`steer` and `cancel` require a running run. They can target chat, task, and
+chore runs.
+
+`rewind` replaces the visible suffix of a branchable chat thread from the
+anchor run onward and starts a replacement run in the same thread. Superseded
+runs remain inspectable by id but are hidden from normal thread projections.
+
+`fork` creates a new chat thread from the context before the anchor run and
+starts one run in the new thread.
+
+Task and chore thread ids are derived from job ids, so job threads cannot be
+rewound or forked. Job execution commands expose explicit job semantics such as
+`task reopen <id>` and `chore run <id>` instead.
+
 
 ## Chat API
 

{toolang-0.2.2 → toolang-0.2.4}/docs/execution.md

@@ -18,15 +18,20 @@ One run is bound to one prepared snapshot for its full lifetime.
 
 ## Durable Store
 
-`runs.db` is the durable store for runtime truth.
+`runs.db` is the durable store for thread and run truth.
 
 It stores:
 
+- threads
 - runs
 - steps
 - agent-local updates
 - deduplicated prompt bodies
 
+`.runtime/jobs.db` stores the scheduler projection for ready task and chore
+documents. It is used for atomic job claims and completion bookkeeping; it is
+not the transcript or run-history store.
+
 
 ## Durable Records
 
@@ -47,8 +52,8 @@ It stores:
 `input` is the canonical initial `Message` for the run.
 
 Toolang-owned run ids use `run_<id>`, where `<id>` is encoded with the `run`
-id family. Thread ids use `<kind>_<id>`, such as `task_3nprht9x`,
-`chore_xy1234ab`, or `web_def456gh`.
+id family. Thread ids use `<kind>_<id>`, such as `tsk_3nprht9x`,
+`chr_xy1234ab`, or `web_def456gh`.
 
 ### StepRecord
 
@@ -87,6 +92,7 @@ Run input is stored as an ordered `inputs` stream. Each input has:
 
 `index = 0` is the `start` input that created the run. Later `steer`
 inputs belong to the same running run and can be referenced by later steps.
+Cancel operations append a `stop` input and then finish the run as canceled.
 
 Step input is an ordered mix of:
 

{toolang-0.2.2 → toolang-0.2.4}/docs/ids.md

@@ -69,11 +69,10 @@ For the `run` family:
 
 The proposed full identities are:
 
-- task thread: `task_<id>`
-- chore thread: `chore_<id>`
+- task thread: `tsk_<id>`
+- chore thread: `chr_<id>`
 - web chat thread: `web_<id>`
 - TUI chat thread: `tui_<id>`
-- agent chat thread: `chat_<id>`
 - Telegram thread: `tg_<external_id>`
 - run id: `run_<id>`
 

{toolang-0.2.2 → toolang-0.2.4}/docs/layout.md

@@ -68,8 +68,9 @@ Key paths:
 | `agent.too` | Agent program |
 | `config.toml` | Agent-local configuration |
 | `psyches/`, `skills/`, `services/`, `prompts/` | Agent-local cap definitions |
-| `tasks/` | Task documents |
-| `chores/` | Chore documents |
+| `tasks/` | Ready task documents |
+| `chores/` | Ready chore documents |
+| `drafts/` | Draft task and chore documents |
 | `archive/` | Retired task and chore documents |
 | `.caps/` | Prepared runtime artifacts |
 | `.runtime/` | Live runtime state |
@@ -88,9 +89,9 @@ Key paths:
 | `status.json` | Runtime status, endpoint, sandbox summary, and enabled features |
 | `agent.log`    | Runtime log                                                  |
 | `logs/<thunk>/<run_id>.log` | Per-run script invoke logs when `PY_LOG` is set |
-| `runs.db` | Runs, steps, updates, and prompt blobs                       |
+| `jobs.db` | Scheduler job projection and atomic job claims                |
+| `runs.db` | Threads, runs, steps, updates, and prompt blobs               |
 | `ids.json`     | Local id allocator state                                     |
-| `pulse.json`   | Pulse loop state                                             |
 | `tools/`       | Per-tool plugin working directories                          |
 | `channels/`    | Per-channel plugin working directories                       |
 
@@ -122,7 +123,8 @@ Durable authored state lives in:
 - agent cap directories
 - agent `tasks/`
 - agent `chores/`
+- agent `drafts/`
 - agent `archive/`
 
 Durable execution state does not live in authored files. It lives in
-`runs.db`.
+`jobs.db` and `runs.db`.