@workerkit/core 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -6,6 +6,131 @@ and the package adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-09-12
+
+### Added
+
+Five manager descriptors: the fleet-operations lane. Reading the state of a
+fleet took a crawl over `workers_list`, `worker_get` and `runs_feed`; the
+account's headroom, a run's raw process log, fan-out and deletion were not
+reachable from the toolset at all. The registry now ships 79 manager and 9
+anonymous descriptors.
+
+- **`fleet_health`** is the digest to brief from. A fleet operated from a chat
+  window rots quietly: workers installed but never deployed while their
+  schedules sit enabled, deployments paused with due times drifting into the
+  past, runs that ended by asking a question nobody saw, last runs refused at
+  the gate. One call returns the counts plus typed sections (`blocked`,
+  `notDeployed`, `overdueSchedules`, `awaitingInput`, `lastRunAttention`), each
+  row naming the worker and the fix. Paused and expired workers are counted,
+  never listed. The question preview inside `awaitingInput` is run content and
+  needs `readRuns`; the rest rides `readWorkers`.
+- **`account_usage`** is the headroom read: plan tier, worker slots,
+  hosted-deployment slots, the wallet's spendable balance with the top-up URL to
+  hand a human, the plan's request windows and settled run spend — so a 402 on
+  `kit_install`, `worker_deploy` or a scheduled run is something an agent plans
+  around rather than discovers. Rides `readWorkers`.
+- **`run_transcript`** reads a run's stored LLM process log, the raw record
+  behind the digest, which was readable only in the dashboard. It is opt-in per
+  deployment (`transcriptRetention`) and kept for 7 days, so the description
+  teaches the agent to read the receipt's `transcriptAvailable` first and to
+  expect 404 `no_transcript` as the normal answer on a worker that never opted
+  in. Rides `readRuns`.
+- **`run_bulk`** fans one prompt out across up to 20 workers in one call, each
+  named by `workerId` (preferred) or its deprecated `tokenId`, on a window of
+  its own (2 calls a minute, 20 an hour per account). Like `worker_clone_bulk`
+  it is not atomic and reports per item — and unlike it, a miss never aborts
+  the batch: an unknown id, a missing deployment or a cap already hit lands on
+  that item and the loop goes on. A Skipped receipt counts as a success (a run
+  was minted; its `skipReason` says why it did not start). Rides `runWorkers`.
+- **`worker_delete`** removes a worker. Deleting existed only in the WorkerKit
+  dashboard, so an agent could create workers — `kit_install`, `worker_clone` —
+  and never remove one, which also left `kit_install`'s 402 worker-cap wall
+  with no fix an agent could apply. It is permanent and not reversible by any
+  call: the key stops working, the schedules stop, and the instruction, memory,
+  deployment and delivery destinations go. Two things the description teaches
+  because an agent gets them wrong by default: deleting an orchestrator deletes
+  its sub-workers too (`subWorkersDeleted` says how many), and
+  `worker_set_enabled` with `enabled:false` is the reversible thing to reach
+  for when someone says "stop" or "turn off". Run receipts survive; the freed
+  slot is the fix for 402 `limit_exceeded`. Requires the new `deleteWorkers`
+  scope.
+
+### Changed
+
+- **`workers_list`** takes filters — `status`, `deployed`, `readiness`, `q` —
+  and answers `totalWorkers` (the unfiltered count, so an empty page is
+  readable). Every row now carries `readiness`, and `lastRun` carries
+  `skipReason` and `errorCode`.
+- **`runs_feed`** and **`worker_runs`**: `awaitingInput` joined the status
+  filter and the outcome vocabulary. The server always accepted it; the closed
+  enum here did not, which made the questions a fleet was waiting on
+  unreachable from the feed.
+- **`budget_get`** and **`budget_set`**: `maxConcurrentRuns` is set by the
+  account's plan — Free 5, Pro 20, Team 50, Enterprise uncapped — rather than
+  fixed at 1, and stays absent from `budget_set` because raising it is an
+  upgrade. It bounds runs started on demand; **`schedule_create`** and
+  **`schedule_update`** now say that a schedule never overlaps itself whatever
+  the plan allows, and **`worker_run`** points to `run_bulk` for fan-out.
+- **`worker_set_enabled`** now names itself as the reversible half of the pair,
+  so the permanent one is never picked by accident, and spells out that
+  stopping an orchestrator cascades to its sub-workers while re-enabling brings
+  back only the parent.
+- **`kit_install`** names `worker_delete` as the second way out of the 402
+  worker-cap wall, to be proposed only with the person's agreement.
+
+### Note
+
+`worker_delete` needs the new `deleteWorkers` scope. Like every scope younger
+than the manager-key surface, a key minted before it existed does not carry
+it — including one minted with "all" — so a 403 there is fixed by an account
+admin re-scoping the key, never by retrying.
+
+## [0.3.1] - 2026-09-11
+
+### Added
+
+Six manager descriptors: the hosted-deployment lane. Deploying a worker existed
+only in the WorkerKit dashboard, so a worker installed through the API, MCP or
+the CLI was created fully configured and could never run — its schedules never
+fired and `worker_run` answered 409 `not_deployed` with nothing in the toolset
+able to fix it. The registry now ships 74 manager and 9 anonymous descriptors.
+
+- **`worker_deploy`** puts a worker on the hosted runtime: pick the model and
+  the per-run / per-day spend ceilings, or send nothing and take the kit's
+  recommended model with the platform defaults. Its refusals are the deploy
+  gauntlet and each names its fix — no instruction, an app still unconnected,
+  an unfunded wallet, a model the account's tier cannot reach.
+- **`deployment_get`** and **`deployments_list`** read one deployment or every
+  deployed worker on the account — the fleet answer to which workers can
+  actually run. A worker in `workers_list` but not here is inert.
+- **`deployment_update`** changes a live deployment (model, reasoning,
+  transcript retention, ceilings) and pauses or resumes it. Pause is the
+  reversible stop that keeps the model and the ceilings.
+- **`worker_undeploy`** takes a worker off the runtime, keeping the worker, its
+  instruction, memory, schedules and its own key.
+- **`models_list`** is the model picker the deployment calls need: what this
+  account may deploy on, priced per million tokens, with the reasoning
+  vocabulary each model accepts and the providers the account holds its own key
+  for.
+
+### Changed
+
+- **`kit_install`** takes `deploy` and `deployment`, so installing and deploying
+  are one call. A deploy refused after the install still returns 201 with
+  `deploymentError` naming what to fix — the worker exists either way, so the
+  fix is `worker_deploy`, never a second install.
+- **`workers_list`** and **`worker_get`** now describe the `deployment` field
+  each worker carries, and that `null` there means the worker will never run
+  whatever its readiness says.
+
+### Note
+
+The deployment writes need the new `manageDeployments` scope. Like every scope
+younger than the manager-key surface, a key minted before it existed does not
+carry it — including one minted with "all" — so a 403 there is fixed by an
+account admin re-scoping the key, never by retrying.
+
 ## [0.3.0] - 2026-09-10
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@
 [![license](https://img.shields.io/npm/l/%40workerkit%2Fcore.svg)](LICENSE)
 
 The shareable [WorkerKit](https://workerkit.ai) surface: an HTTP API client, the
-declarative tool-descriptor registry (68 authenticated fleet-management tools +
+declarative tool-descriptor registry (79 authenticated fleet-management tools +
 9 anonymous kits-directory tools), and the single wire-execution path that turns
 a descriptor plus parameters into exactly one upstream request.
 

package/dist/descriptors/index.d.ts

@@ -3,7 +3,7 @@ export type { HttpMethod, ToolAnnotations, ToolDescriptor } from "./types.js";
 export { manageDescriptors } from "./manage.js";
 export { directoryDescriptors, kitDetailData, kitDetailFooter, kitListData, listFooter, publisherPageData, publisherPageFooter, } from "./directory.js";
 import type { ToolDescriptor } from "./types.js";
-/** Every descriptor this package ships — 68 manager + 9 anonymous. */
+/** Every descriptor this package ships — 79 manager + 9 anonymous. */
 export declare const allDescriptors: readonly ToolDescriptor[];
 /** Look a descriptor up by its tool name. */
 export declare function byName(name: string): ToolDescriptor | undefined;

package/dist/descriptors/index.js

@@ -3,7 +3,7 @@ export { manageDescriptors } from "./manage.js";
 export { directoryDescriptors, kitDetailData, kitDetailFooter, kitListData, listFooter, publisherPageData, publisherPageFooter, } from "./directory.js";
 import { manageDescriptors } from "./manage.js";
 import { directoryDescriptors } from "./directory.js";
-/** Every descriptor this package ships — 68 manager + 9 anonymous. */
+/** Every descriptor this package ships — 79 manager + 9 anonymous. */
 export const allDescriptors = [
     ...manageDescriptors,
     ...directoryDescriptors,

package/dist/descriptors/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/descriptors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EACN,SAAS,EACT,OAAO,EACP,MAAM,GACP,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAA8B;IACvD,GAAG,iBAAiB;IACpB,GAAG,oBAAoB;CACxB,CAAC;AAEF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpE,6CAA6C;AAC7C,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC","sourcesContent":["export {\n  CREATE,\n  DELETE,\n  READ_ONLY,\n  TRIGGER,\n  UPDATE,\n} from \"./types.js\";\nexport type { HttpMethod, ToolAnnotations, ToolDescriptor } from \"./types.js\";\n\nexport { manageDescriptors } from \"./manage.js\";\nexport {\n  directoryDescriptors,\n  kitDetailData,\n  kitDetailFooter,\n  kitListData,\n  listFooter,\n  publisherPageData,\n  publisherPageFooter,\n} from \"./directory.js\";\n\nimport type { ToolDescriptor } from \"./types.js\";\nimport { manageDescriptors } from \"./manage.js\";\nimport { directoryDescriptors } from \"./directory.js\";\n\n/** Every descriptor this package ships — 68 manager + 9 anonymous. */\nexport const allDescriptors: readonly ToolDescriptor[] = [\n  ...manageDescriptors,\n  ...directoryDescriptors,\n];\n\nconst byNameIndex = new Map(allDescriptors.map((d) => [d.name, d]));\n\n/** Look a descriptor up by its tool name. */\nexport function byName(name: string): ToolDescriptor | undefined {\n  return byNameIndex.get(name);\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/descriptors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EACN,SAAS,EACT,OAAO,EACP,MAAM,GACP,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAA8B;IACvD,GAAG,iBAAiB;IACpB,GAAG,oBAAoB;CACxB,CAAC;AAEF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpE,6CAA6C;AAC7C,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC","sourcesContent":["export {\n  CREATE,\n  DELETE,\n  READ_ONLY,\n  TRIGGER,\n  UPDATE,\n} from \"./types.js\";\nexport type { HttpMethod, ToolAnnotations, ToolDescriptor } from \"./types.js\";\n\nexport { manageDescriptors } from \"./manage.js\";\nexport {\n  directoryDescriptors,\n  kitDetailData,\n  kitDetailFooter,\n  kitListData,\n  listFooter,\n  publisherPageData,\n  publisherPageFooter,\n} from \"./directory.js\";\n\nimport type { ToolDescriptor } from \"./types.js\";\nimport { manageDescriptors } from \"./manage.js\";\nimport { directoryDescriptors } from \"./directory.js\";\n\n/** Every descriptor this package ships — 79 manager + 9 anonymous. */\nexport const allDescriptors: readonly ToolDescriptor[] = [\n  ...manageDescriptors,\n  ...directoryDescriptors,\n];\n\nconst byNameIndex = new Map(allDescriptors.map((d) => [d.name, d]));\n\n/** Look a descriptor up by its tool name. */\nexport function byName(name: string): ToolDescriptor | undefined {\n  return byNameIndex.get(name);\n}\n"]}

package/dist/descriptors/manage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manage.d.ts","sourceRoot":"","sources":["../../src/descriptors/manage.ts"],"names":[],"mappings":"AAMA,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AA2pD7F,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAqEtD,CAAC"}
+{"version":3,"file":"manage.d.ts","sourceRoot":"","sources":["../../src/descriptors/manage.ts"],"names":[],"mappings":"AAMA,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAi7D7F,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAgFtD,CAAC"}