anbaric 1.56.8 → 1.56.9

package/docs/api/cli.md

@@ -46,7 +46,7 @@ anbaric app status link-media-brief     # a different app, from anywhere
 | --- | --- |
 | `anbaric state-machines` | List registered state machines. |
 | `anbaric jobs create <sm-id> <start-state> [k=v …]` | Create a job and queue it for processing. |
-| `anbaric jobs list [state-machine-id]` | List jobs, optionally filtered by workflow. |
+| `anbaric jobs list [state-machine-id]` | List jobs, newest first, a page at a time (100 by default — `--page 1` for the next). Narrow with `--state`, `--status`, `--app`; `--oldest` flips the order. Filters apply on the platform, across every job, before paging. |
 | `anbaric jobs stats` | Job counts per state and the queue size. |
 | `anbaric jobs watch <job-id>` | Follow a job's state and property changes live. |
 | `anbaric jobs set-state <job-id> <state>` | Move a job to a state and re-queue it. |
@@ -67,6 +67,9 @@ ask for, so the CLI runs unattended in scripts and CI.
 | `--name <name>` | `app configure`/`deploy`/`update` | App name; prompts if omitted (suggested from `package.json`). |
 | `--port <port>` | `app configure`/`deploy`/`update` | Internal port (1–65535); prompts if omitted. |
 | `--yes` | `app deploy`, `app tear-down`, `jobs kill-old` | Skip confirmation. (`app update` implies it.) |
+| `--state <state>`, `--status <status>`, `--app <app>` | `jobs list` | Only jobs in that state / with that status (`active`, `Awaiting input`, `Failed`) / belonging to that app. |
+| `--page <n>`, `--page-size <n>` | `jobs list` | Which page (from 0) and how many per page (default 100). |
+| `--oldest` | `jobs list` | Oldest first instead of newest. |
 | `--help`, `-h` | all | Print usage. |
 
 ## Configuration and storage

package/docs/api/state-machine.md

@@ -268,6 +268,30 @@ A job whose action threw is `FAILED`, with the reason in its audit trail. It
 stays in its state rather than transitioning, and an update that moves it on
 returns it to `ACTIVE` — so a failure is recoverable, not terminal.
 
+### Listing jobs
+
+```ts
+const persistence = JobPersistenceFactory.instance();
+
+persistence.list(actor) : Promise<Array<Job>>                                  // first 100, oldest first
+persistence.list(actor, pageSize, page, query?) : Promise<Array<Job>>
+
+type JobPersistence.Query = {
+    workflowId? : string,
+    appId? : string,
+    state? : string,
+    status? : string,            // "active", "Awaiting input", "Failed"
+    killed? : boolean,
+    order? : "oldest" | "newest" // by when the job was started; oldest by default
+}
+```
+
+A listing is a **page**, never a cap: `pageSize` jobs (default 100) at `page`
+(from 0), and every job the store holds is reachable by asking for the next
+page until one comes back short. The query narrows the set on the store before
+paging — a filter sees every job, and page numbers count matching jobs only.
+Deployed, the store holds every job on the tenant across all apps and machines.
+
 ---
 
 ## `PropertyDefinition`

package/docs/api/web.md

@@ -94,10 +94,32 @@ GET /api/v2/whoami   →   { "id": "user-123", "roles": ["admin"] }
 
 Returns the authenticated user for the current request.
 
+### Jobs
+
+```
+GET /api/v2/jobs?page=0&pageSize=100&order=newest&workflowId=…&appId=…&state=…&status=…&killed=false
+```
+
+Every job on the tenant, across all apps and state machines, **paged**: the
+response is one page of at most `pageSize` jobs (default 100) at page `page`
+(from 0). The page size is not a cap — keep asking for the next page until one
+comes back shorter than `pageSize`, which is the last. `order` is by when the
+job was started: `oldest` (the default, for compatibility) or `newest`.
+
+The other parameters are filters, applied on the platform **before** paging, so
+a filter sees every job and page numbers count matching jobs only. All are
+optional and combine with AND: `workflowId` (the state machine), `appId`,
+`state`, `status` (`active`, `Awaiting input`, `Failed`) and `killed`
+(`true`/`false`).
+
+In code the same listing is `JobPersistenceFactory.instance().list(actor,
+pageSize, page, query)`; the CLI's `anbaric jobs list` and the MCP tool
+`anbaric_jobs_list` take the same filters.
+
 ### Other resources
 
 Also under `/api/v2`, reached through the cloud clients rather than raw HTTP:
-`jobs`, `state-machines`, `queue`, `consumers`, and (when enabled) `documents`,
+`state-machines`, `queue`, `consumers`, and (when enabled) `documents`,
 `secrets`, `audits`. Prefer the typed clients and factories over calling these by
 hand.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.56.8",
+  "version": "1.56.9",
   "description": "Everything needed to write an Anbaric app: state machines, jobs, document and secret stores, local in-memory implementations and the Anbaric Cloud clients",
   "license": "MIT",
   "type": "module",
@@ -24,9 +24,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "anbaric-impl-cloud": "^1.56.8",
-    "anbaric-data-store": "^1.56.8",
-    "anbaric-state-machine": "^1.56.8",
-    "anbaric-tsapi": "^1.56.8"
+    "anbaric-impl-cloud": "^1.56.9",
+    "anbaric-data-store": "^1.56.9",
+    "anbaric-state-machine": "^1.56.9",
+    "anbaric-tsapi": "^1.56.9"
   }
 }