@workerkit/core 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -6,6 +6,38 @@ and the package adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-09-18
+
+### Added
+
+- **`worker_run`** takes `answers` on a decision worker: values laid over the
+  worker's stored install answers for THIS run only, never saved. It is how
+  one caller names a searcher kit's target without touching the worker's
+  setup, so two callers sharing a worker never see each other's. The map is
+  validated against the kit's own form the way `instruction_set` validates it
+  and bound the way the run will bind it, so a row that cannot bind (a
+  category clashing with a built-in option, a ladder outside 2–10 levels) is a
+  400 naming it here rather than a run that fails later. A list question takes
+  a JSON array string or `;`-separated rows, and a question left unnamed keeps
+  its stored answer or the kit's default.
+
+### Changed
+
+- **`worker_run`**'s `sourceArgs` names relative window bounds, `after:
+  "-14d"` or `endDate: "+48h"`, which the platform resolves when the read
+  runs. That is the form to use for "the last N days" instead of computing a
+  date in the caller.
+- The `decision` block on **`run_get`** and a waited **`worker_run`** carries
+  `model`, the decision-model version that actually answered, worth citing
+  when behaviour changes, and `answersOverride`, the per-run answers the run
+  was minted with.
+- `findings[]` in that block is led by the source's own caveat when a read was
+  partial or withheld, a rate-limited mailbox or a firewall rule, so "nothing
+  found" is never trusted over a page that was never fully read.
+- **`instruction_set`**'s `answers` and **`kit_install`**'s `decisionAnswers`
+  take `;`-separated list rows as well as one per line, and say that clearing
+  a question falls back to its default where the kit ships one.
+
 ## [0.3.3] - 2026-09-18
 
 ### Added

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;AA69D7F,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAgFtD,CAAC"}
+{"version":3,"file":"manage.d.ts","sourceRoot":"","sources":["../../src/descriptors/manage.ts"],"names":[],"mappings":"AAMA,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAi+D7F,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAgFtD,CAAC"}

package/dist/descriptors/manage.js

@@ -18,7 +18,7 @@ const RUNTIME_NOTE = " 422 RUNTIME_NOT_ENABLED = hosted runs are switched off in
 const UTC_HINT = "ISO 8601 UTC datetime, e.g. '2026-08-01T00:00:00Z'.";
 // What a decision worker's receipt carries beyond an agent run's: taught on the
 // two tools that hand a receipt back.
-const DECISION_BLOCK_NOTE = " A DECISION worker's receipt carries a `decision` block: outcome (one line: how many judged, routed, below the floor, acted on), confidence (share of judged items ABOVE the confidence floor, 0–100 — not a self-score), calls, and decisions[] — one row per judged item: id, answers (question → the model's label or number), confidence, route (rule:N, else, or below_floor: not sure, escalated to the owner), action (call <tool> / escalate / none) and, in live, executed/ok. findings[] are per-question distributions, openQuestions[] the items a person should look at. The block is run CONTENT: it needs readRuns; without it the block comes back withheld (contentWithheld:true) while status, timings and cost still answer.";
+const DECISION_BLOCK_NOTE = " A DECISION worker's receipt carries a `decision` block: outcome (one line: how many judged, routed, below the floor, acted on), confidence (share of judged items ABOVE the confidence floor, 0–100 — not a self-score), calls, model (the decision-model version that actually answered, e.g. jev-1.13.0 — cite it when behaviour changes), answersOverride (the per-run answers the run was minted with, when any) and decisions[] — one row per judged item: id, answers (question → the model's label or number), confidence, route (rule:N, else, or below_floor: not sure, escalated to the owner), action (call <tool> / escalate / none) and, in live, executed/ok. findings[] are per-question distributions — led, when the source read was partial or withheld (a rate-limited mailbox, a firewall rule), by the source's own caveat, so 'nothing found' is never trusted over a page that was never fully read; openQuestions[] the items a person should look at. The block is run CONTENT: it needs readRuns; without it the block comes back withheld (contentWithheld:true) while status, timings and cost still answer.";
 // A scope added to the product AFTER a key was minted never reaches that key —
 // including a key minted with "all", which stored the bitmask of the scopes that
 // existed that day. Taught on key_info and on every tool behind a scope that is
@@ -89,7 +89,7 @@ const getWorker = {
 const runWorker = {
     name: "worker_run",
     title: "Run Worker Now",
-    description: "Trigger the worker to run now (recorded as an API-triggered run, attributed to the manager key's minter). The response is the minted run's RECEIPT — read status before assuming it ran: policy rejections (kill switch, usage window, daily run/spend cap, concurrency, wallet credits, readiness, or a rejected BYOK provider key) come back as HTTP 200 with status Skipped and a skipReason telling the story; that is a normal receipt, NOT an error. Most skips clear on their own (a cap resets, concurrency frees up, credits top up) — but skipReason 'ByokKeyInvalid' / errorCode 'byok_key_invalid' means the ACCOUNT's own model-provider API key was rejected by the provider, arrives with errorDetail null (no prose), and is owner-fixable ONLY: never retry it, report it to the human so they can re-add or remove the key. Structural refusals are 409 (not_deployed, deployment_paused, deployment_suspended, model_unavailable) and 404 for an unknown worker; run-endpoint errors use the {error, message} envelope where error IS the snake_case code. prompt = what to do THIS run; omit it and the worker runs on its standing instructions. Rate limit: 30 run-triggers per minute per ACCOUNT (all of this account's keys and clients share it; other accounts do not affect you). On a 429 back off for the Retry-After — never tighten a loop in response. To fan one prompt across many workers, run_bulk takes up to 20 in one call on a window of its own. Runs in flight per worker are bounded by the account's plan (Free 5, Pro 20, Team 50); at that limit this answers a Skipped receipt with skipReason ConcurrencyLimit. The worker's model type (worker_get → modelType) decides which fields apply: a LANGUAGE worker takes prompt and modelSlug; a DECISION worker runs its own routing table and takes neither (409 not_language_worker), taking preview / sourceArgs / maxItems instead — and sending those to a language worker is 409 not_decision_worker." +
+    description: "Trigger the worker to run now (recorded as an API-triggered run, attributed to the manager key's minter). The response is the minted run's RECEIPT — read status before assuming it ran: policy rejections (kill switch, usage window, daily run/spend cap, concurrency, wallet credits, readiness, or a rejected BYOK provider key) come back as HTTP 200 with status Skipped and a skipReason telling the story; that is a normal receipt, NOT an error. Most skips clear on their own (a cap resets, concurrency frees up, credits top up) — but skipReason 'ByokKeyInvalid' / errorCode 'byok_key_invalid' means the ACCOUNT's own model-provider API key was rejected by the provider, arrives with errorDetail null (no prose), and is owner-fixable ONLY: never retry it, report it to the human so they can re-add or remove the key. Structural refusals are 409 (not_deployed, deployment_paused, deployment_suspended, model_unavailable) and 404 for an unknown worker; run-endpoint errors use the {error, message} envelope where error IS the snake_case code. prompt = what to do THIS run; omit it and the worker runs on its standing instructions. Rate limit: 30 run-triggers per minute per ACCOUNT (all of this account's keys and clients share it; other accounts do not affect you). On a 429 back off for the Retry-After — never tighten a loop in response. To fan one prompt across many workers, run_bulk takes up to 20 in one call on a window of its own. Runs in flight per worker are bounded by the account's plan (Free 5, Pro 20, Team 50); at that limit this answers a Skipped receipt with skipReason ConcurrencyLimit. The worker's model type (worker_get → modelType) decides which fields apply: a LANGUAGE worker takes prompt and modelSlug; a DECISION worker runs its own routing table and takes neither (409 not_language_worker), taking preview / sourceArgs / answers / maxItems instead — and sending those to a language worker is 409 not_decision_worker." +
         DECISION_BLOCK_NOTE +
         RUNTIME_NOTE,
     auth: "manager",
@@ -99,7 +99,8 @@ const runWorker = {
         prompt: z.string().max(8000).optional().describe("Language workers: what to do on THIS run (≤8000 chars). Omit to run the worker's standing instructions unchanged."),
         modelSlug: z.string().max(64).optional().describe("Language workers: one-off model override for this run (≤64 chars). Omit to use the worker's configured model."),
         preview: z.boolean().optional().describe("Decision workers: run THIS run in preview whatever the deployment's mode — every row says what the worker WOULD do and nothing is done. Live is never forced the other way, and it costs the same decision-model calls as a real run."),
-        sourceArgs: z.record(z.string(), z.unknown()).optional().describe("Decision workers: narrow what is decided about — values merged over the spec's source arguments for THIS run only (a ticket id, a query, a status). A plain object, no placeholders; the read still runs under the worker's own permissions, so it can only see what the worker can."),
+        sourceArgs: z.record(z.string(), z.unknown()).optional().describe("Decision workers: narrow what is decided about — values merged over the spec's source arguments for THIS run only (a ticket id, a query, a status, a window such as after: \"-14d\" or endDate: \"+48h\" — relative bounds are resolved by the platform when the read runs, so never compute a date). A plain object, no placeholders; the read still runs under the worker's own permissions, so it can only see what the worker can."),
+        answers: z.record(z.string(), z.string()).optional().describe("Decision workers: answers to the worker's install questions for THIS run only, laid over its stored answers per key and never saved — how a caller names a searcher kit's target ({ \"target-name\": \"Acme Corp\" }) without touching the worker's setup, so two callers on one worker never see each other's. Validated against the kit's own form like instruction_set and bound the way the run will bind them, so a row that cannot bind (a category clashing with a built-in option, a ladder outside 2–10 levels) is a 400 naming it here, never a failed run. A list question takes a JSON array string or ';'-separated rows; a question not named keeps its stored answer or the kit's default."),
         maxItems: z.number().int().min(1).max(100000).optional().describe("Decision workers: judge at most this many items this run (never above the spec's own cap). ~20 reads as a table; omit for the spec's limit."),
         waitSeconds: z.number().int().min(0).max(55).optional().describe("Hold the call until the run settles and answer the settled receipt (0–55) — worth it on a decision worker, whose runs are seconds. Omit and the answer is the just-minted receipt, followed with run_get. Past the deadline the receipt comes back with a non-terminal status: poll run_get."),
     },
@@ -109,6 +110,7 @@ const runWorker = {
         modelSlug: params.modelSlug,
         preview: params.preview,
         sourceArgs: params.sourceArgs,
+        answers: params.answers,
         maxItems: params.maxItems,
         waitSeconds: params.waitSeconds,
     }),
@@ -660,7 +662,7 @@ const setInstruction = {
     schema: {
         tokenId: z.number().int().min(1).describe(TOKEN_ID_HINT),
         content: z.string().min(1).max(100000).optional().describe("Language workers: the instruction text (1–100,000 chars) — replaces the whole content."),
-        answers: z.record(z.string(), z.string().max(4000)).optional().describe("Decision workers: install answers by question key, from instruction_get's setup[]. A PARTIAL map changes only the keys it names; '' clears one. A scale takes a stop's label, a choice an option's value, a list one row per line, an appPick an id (instruction_get's optionsFor lists the live ones). An unknown key or an off-menu value is a 400 naming it; 409 on a language-model worker."),
+        answers: z.record(z.string(), z.string().max(4000)).optional().describe("Decision workers: install answers by question key, from instruction_get's setup[]. A PARTIAL map changes only the keys it names; '' clears one (a question with a default falls back to it). A scale takes a stop's label, a choice an option's value, a list one row per line or ';'-separated, an appPick an id (instruction_get's optionsFor lists the live ones). An unknown key or an off-menu value is a 400 naming it; 409 on a language-model worker."),
         jobSentence: z.string().max(200).optional().describe("The worker's one-liner (≤200). Omit = unchanged; '' = clear."),
         whenToUse: z.string().max(500).optional().describe("Trigger text: when this worker should be used (≤500). Omit = unchanged; '' = clear."),
         description: z.string().max(2000).optional().describe("Longer display-only description (≤2000). Omit = unchanged; '' = clear."),
@@ -799,7 +801,7 @@ const kitInstall = {
         })).optional().describe("One entry per categorySlots slot. Omitted slots resolve to the kit's first offered member on safe defaults."),
         inputs: z.record(z.string(), z.string()).optional().describe("Answers to requiredInputs, keyed EXACTLY by each entry's key. Every key is mandatory; values are single-line, 1-200 chars."),
         memoryAnswers: z.record(z.string(), z.string()).optional().describe("Answers to memorySetup questions by key. Entries with required:true are mandatory. Keep this separate from inputs — mixing the two maps is a 400."),
-        decisionAnswers: z.record(z.string(), z.string()).optional().describe("DECISION kits only: answers to the preview's decisionSetup questions by key — a choice takes an option's value, a scale a stop's label (or its value), a list one row per line (≤20 rows), an appPick an id (or leave it blank and answer it later with instruction_set); text and rows ≤200 chars. A required question with no default and no answer is a 400 naming it."),
+        decisionAnswers: z.record(z.string(), z.string()).optional().describe("DECISION kits only: answers to the preview's decisionSetup questions by key — a choice takes an option's value, a scale a stop's label (or its value), a list one row per line or ';'-separated (≤20 rows; a list with a built-in default keeps it when left blank — the template classifiers ship their categories that way), an appPick an id (or leave it blank and answer it later with instruction_set); text and rows ≤200 chars. A required question with no default and no answer is a 400 naming it."),
         deploy: z.boolean().optional().describe("true = also put the new worker on the hosted runtime, so it actually runs. Without this the install creates a worker that fires no schedule and refuses worker_run with not_deployed. Needs the manageDeployments scope."),
         deployment: z.object({
             modelSlug: z.string().max(64).optional().describe("Model to deploy on, from models_list. Omit for the kit's recommended model."),