@workerkit/core 0.3.20 → 0.3.22

package/dist/descriptors/manage.js

@@ -11,8 +11,9 @@ import { createDecisionWorker } from "./decision-authoring.js";
 import { onboardingDescriptors } from "./onboarding.js";
 import { supportDescriptors } from "./support.js";
 import { qualityDescriptors } from "./quality.js";
+import { knowledgeDescriptors } from "./knowledge.js";
 import { z } from "../zod.js";
-import { guidance, scopeReviewAction, runModelHint, publicKitPublishingPause } from "../guidance.js";
+import { guidance, creationResultGuidance, managerAuthorityPreflight, scopeReviewAction, runModelHint, publicKitPublishingPause } from "../guidance.js";
 import { defineTool, CREATE, DELETE, READ_ONLY, TRIGGER, UPDATE } from "./types.js";
 // The graded-outcome vocabulary, taught wherever a score can be read or written.
 // The null-vs-zero line is the one an agent gets wrong by default: absent means
@@ -70,7 +71,7 @@ const getKeyInfo = defineTool({
 const listWorkers = defineTool({
     name: "workers_list",
     title: "List Workers",
-    description: "List reachable workers with title/avatar, active|paused|expired status, isEnabled/expiresAt, ready|blocked readiness/issues, modelType (worker_get explains), deployment, schedules(total/enabled/nextRunUtc), live isRunning/inFlightRuns/currentRunId (watch with run_get), and lastRun. lastRun is the newest SETTLED receipt only: runId, initiator (who started it: user, fleetKey as an id/name/prefix snapshot, schedule, webhook or worker; historicalUnknown when unrecorded), succeeded|attention|failed|awaitingInput|skipped|canceled outcome, skipReason/errorCode. Null deployment means no hosted runs despite readiness: worker_deploy, except Action (modelType none), which uses worker_tools/worker_tool_call. Optional filters AND: status, deployed, readiness, q (title substring); unknown status/readiness is 400 invalid_filter. totalWorkers counts BEFORE filters within key reach: zero means no reachable installs; nonzero plus empty workers[] means no filter matches. key_info shows restricted selection; to install, kits_search then kit_install(deploy:true), which adds the new worker to a restricted key's selection. Use fleet_health for fleet problems and serverTimeUtc for elapsed/next-run time. {{scope}} lastRun.resultText additionally needs readRuns. A null without readRuns means withheld, not an absent report. Check key_info; never automatically retry a 403.",
+    description: managerAuthorityPreflight + "List reachable workers with title/avatar, active|paused|expired status, isEnabled/expiresAt, ready|blocked readiness/issues, modelType (worker_get explains), deployment, schedules(total/enabled/nextRunUtc), live isRunning/inFlightRuns/currentRunId (watch with run_get), and lastRun. lastRun is the newest SETTLED receipt only: runId, initiator (who started it: user, fleetKey as an id/name/prefix snapshot, schedule, webhook or worker; historicalUnknown when unrecorded), succeeded|attention|failed|awaitingInput|skipped|canceled outcome, skipReason/errorCode. Null deployment means no hosted runs despite readiness: worker_deploy, except Action (modelType none), which uses worker_tools/worker_tool_call. Optional filters AND: status, deployed, readiness, q (title substring); unknown status/readiness is 400 invalid_filter. totalWorkers counts BEFORE filters within key reach: zero means no reachable installs; nonzero plus empty workers[] means no filter matches. key_info shows restricted selection; to install, kits_search then kit_install(deploy:true), which adds the new worker to a restricted key's selection. Use fleet_health for fleet problems and serverTimeUtc for elapsed/next-run time. {{scope}} lastRun.resultText additionally needs readRuns. A null without readRuns means withheld, not an absent report. Check key_info; never automatically retry a 403.",
     auth: "manager",
     method: "get",
     schema: {
@@ -86,7 +87,7 @@ const listWorkers = defineTool({
 const fleetHealth = defineTool({
     name: "fleet_health",
     title: "Fleet Health",
-    description: "Diagnose the reachable fleet in one read instead of crawling workers and runs. {{scope}} Returns serverTimeUtc, counts(workers/active/paused/expired/runsInFlight and section totals), and five sections with workerId/tokenId/title and fixes. blocked: active workers with readiness issues; app_not_connected -> app_connect on their operator/dashboard, no_instruction -> instruction_set, no_identity -> dashboard, action_connection_unavailable/action_tools_unavailable -> owner/dashboard. notDeployed: active hosted workers only (never Action); no schedule/run can execute until worker_deploy; enabledSchedules and readiness show impact. overdueSchedules: deployed workers with an unclaimed fire >15 minutes overdue; nextRunUtc/overdueMinutes/deploymentStatus (Paused -> deployment_update resume). awaitingInput: open questions with questionId/runId/askedAtUtc/expiresAtUtc/chainDepth; question is a 300-char preview needing readRuns, otherwise null means withheld, not empty. run_question reads full text/options; run_answer uses runId. lastRunAttention: active workers whose latest settled outcome is failed(errorCode), attention(success with denials/tool errors/issues), or skipped(skipReason; InsufficientCredits means wallet, TokenDisabled/DailyRunCap/FleetSpendCap name the gate). Paused/expired workers are counted, not listed as problems. Empty sections are healthy; compute ages against serverTimeUtc.",
+    description: managerAuthorityPreflight + "Diagnose the reachable fleet in one read instead of crawling workers and runs. {{scope}} Returns serverTimeUtc, counts(workers/active/paused/expired/runsInFlight and section totals), and five sections with workerId/tokenId/title and fixes. blocked: active workers with readiness issues; app_not_connected -> app_connect on their operator/dashboard, no_instruction -> instruction_set, no_identity -> dashboard, action_connection_unavailable/action_tools_unavailable -> owner/dashboard. notDeployed: active hosted workers only (never Action); no schedule/run can execute until worker_deploy; enabledSchedules and readiness show impact. overdueSchedules: deployed workers with an unclaimed fire >15 minutes overdue; nextRunUtc/overdueMinutes/deploymentStatus (Paused -> deployment_update resume). awaitingInput: open questions with questionId/runId/askedAtUtc/expiresAtUtc/chainDepth; question is a 300-char preview needing readRuns, otherwise null means withheld, not empty. run_question reads full text/options; run_answer uses runId. lastRunAttention: active workers whose latest settled outcome is failed(errorCode), attention(success with denials/tool errors/issues), or skipped(skipReason; InsufficientCredits means wallet, TokenDisabled/DailyRunCap/FleetSpendCap name the gate). Paused/expired workers are counted, not listed as problems. Empty sections are healthy; compute ages against serverTimeUtc.",
     auth: "manager",
     method: "get",
     schema: {},
@@ -96,7 +97,7 @@ const fleetHealth = defineTool({
 const accountUsage = defineTool({
     name: "account_usage",
     title: "Account Usage",
-    description: "Read headroom before installing, deploying or running. {{scope}} 404 means no active operator. Returns default install operator and per-operator limits; plan tier free|pro|team|enterprise, complimentaryUntilUtc for temporary grants; workers{used,max,remaining} (zero: install/clone/re-enable 402 limit_exceeded; delete frees a slot or upgrade); hostedWorkers{used,max,remaining} (deploy cap; suspended deployments excluded). wallet has spendableBalanceUsd/promoRemainingUsd/promoExpiresAtUtc/topUpUrl; zero causes deploy 402 wallet_required or scheduled Skipped/InsufficientCredits. AN AGENT CANNOT TOP IT UP WITHOUT HUMAN PAYMENT: requestWalletTopUp permits wallet_checkout_create; otherwise show topUpUrl. requests.daily/hourly/monthly has limit/used/remaining/resetsAt for worker-to-app data-plane calls; limit 0 means DISABLED, not exhausted. spend(todayUsd/thisMonthUsd/reservedInFlightUsd) is settled run spend plus holds, null if runtime disabled. Account-owned spend ceilings: fleet_budget_get.",
+    description: managerAuthorityPreflight + "Read headroom before installing, deploying or running. {{scope}} 404 means no active operator. Returns default install operator and per-operator limits; plan tier free|pro|team|enterprise, complimentaryUntilUtc for temporary grants; workers{used,max,remaining} (zero: install/clone/re-enable 402 limit_exceeded; delete frees a slot or upgrade); hostedWorkers{used,max,remaining} (deploy cap; suspended deployments excluded). wallet has spendableBalanceUsd/promoRemainingUsd/promoExpiresAtUtc/topUpUrl; zero causes deploy 402 wallet_required or scheduled Skipped/InsufficientCredits. AN AGENT CANNOT TOP IT UP WITHOUT HUMAN PAYMENT: requestWalletTopUp permits wallet_checkout_create; otherwise show topUpUrl. requests.daily/hourly/monthly has limit/used/remaining/resetsAt for worker-to-app data-plane calls; limit 0 means DISABLED, not exhausted. spend(todayUsd/thisMonthUsd/reservedInFlightUsd) is settled run spend plus holds, null if runtime disabled. Wallet balance alone does not establish readiness or deployment. Account-owned spend ceilings: fleet_budget_get.",
     auth: "manager",
     method: "get",
     schema: {},
@@ -152,7 +153,7 @@ const activitySummary = defineTool({
 const getWorker = defineTool({
     name: "worker_get",
     title: "Get Worker",
-    description: "Read worker detail, including all workers_list fields, timeZoneId, maxRunsPerDay, kit templateId/slug/name, hasInstruction, isProtected and jobSentence. {{scope}} readiness is ready|blocked with issues (worker_inactive, no_identity, app_not_connected with candidateProviders, no_instruction, action_connection_unavailable/action_tools_unavailable, worker_slots_pending when a required worker slot is unbound: worker_bindings_set fills it); canRun means hosted readiness, canInvoke means Action readiness. modelType: language runs prose on a model; decision runs a routing table (instruction_get/worker_run; decisionPendingSetup names unanswered setup); hybrid classifies then passes selected items to one language agent; none is Action (no model, deployment or run; worker_run/worker_deploy return 400 action_worker_requires_invoke; use worker_tools/worker_tool_call). apps[] lists enabled apps, providers and connected|needs_connection|unknown; fix needs_connection with app_connect on this worker's operator or dashboard. deployment has status/modelSlug; null means no hosted execution regardless of readiness (worker_deploy fixes it, except Action). Activity covers 30-day outcomes/success rate/cost; null when hosted runtime is disabled.",
+    description: managerAuthorityPreflight + "Read worker detail, including all workers_list fields, timeZoneId, maxRunsPerDay, kit templateId/slug/name, hasInstruction, isProtected and jobSentence. {{scope}} readiness is ready|blocked with issues (worker_inactive, no_identity, app_not_connected with candidateProviders, no_instruction, action_connection_unavailable/action_tools_unavailable, worker_slots_pending when a required worker slot is unbound: worker_bindings_set fills it; personal_connection_not_shared when a linked identity has another member's personal OAuth: unlink that identity or use the worker owner's own identity); canRun means hosted readiness, canInvoke means Action readiness. modelType: language runs prose on a model; decision runs a routing table (instruction_get/worker_run; decisionPendingSetup names unanswered setup); hybrid classifies then passes selected items to one language agent; none is Action (no model, deployment or run; worker_run/worker_deploy return 400 action_worker_requires_invoke; use worker_tools/worker_tool_call). apps[] lists enabled apps, providers and connected|needs_connection|unknown; fix needs_connection with app_connect on this worker's operator or dashboard. deployment has status/modelSlug; null means no hosted execution regardless of readiness (worker_deploy fixes it, except Action). Activity covers 30-day outcomes/success rate/cost; null when hosted runtime is disabled.",
     auth: "manager",
     method: "get",
     schema: {
@@ -172,7 +173,7 @@ const runWorker = defineTool({
     requestTimeoutMs: (params) => typeof params.waitSeconds === "number"
         ? Math.max(30_000, (Math.min(55, Math.max(0, params.waitSeconds)) + 5) * 1000) : undefined,
     title: "Run Worker Now",
-    description: "Run now, API-triggered and attributed to the exact fleet key and its accountable subject user. Never automatically repeat an uncertain write. {{scope}} Read the receipt's status: policy refusals (kill switch, usage window, run/spend cap, concurrency, wallet, readiness, BYOK key) return HTTP 200 Skipped with skipReason, a normal receipt, not an error. " + guidance.spendCap + " Most clear with reset/capacity/funding. ByokKeyInvalid/byok_key_invalid with errorDetail:null requires the human to re-add/remove the ACCOUNT's rejected provider key; never retry. Structural refusals: 409 not_deployed/deployment_paused/deployment_suspended/model_unavailable; 404 unreachable worker. Error envelope: {error,message}, with snake_case code in error. prompt overrides this run; omit for standing instructions. Account-wide limit: 30 triggers/min across keys/clients; other accounts do not affect you. On 429 honor Retry-After. run_bulk fans out to 20 workers on a separate window. In-flight worker limit: Free 5/Pro 20/Team 50; excess yields Skipped/ConcurrencyLimit. Language accepts prompt/modelSlug; decision accepts sourceArgs/answers/maxItems instead (wrong kind: 409 not_language_worker/not_decision_worker). Hybrid accepts both: it classifies a bounded window then runs one language agent on selected items, returning one receipt; manual/on-demand only. Classified receipts include coverage and committed wallet cost. Action (modelType none): 400 action_worker_requires_invoke; use worker_tool_call." + RUNTIME_NOTE,
+    description: managerAuthorityPreflight + "Run now, API-triggered and attributed to the exact fleet key and its accountable subject user. Never automatically repeat an uncertain write. {{scope}} Read the receipt's status: policy refusals (kill switch, usage window, run/spend cap, concurrency, wallet, readiness, BYOK key) return HTTP 200 Skipped with skipReason, a normal receipt, not an error. " + guidance.spendCap + " Most clear with reset/capacity/funding. ByokKeyInvalid/byok_key_invalid with errorDetail:null requires the human to re-add/remove the ACCOUNT's rejected provider key; never retry. Structural refusals: 409 not_deployed/deployment_paused/deployment_suspended/model_unavailable; 404 unreachable worker. Error envelope: {error,message}, with snake_case code in error. prompt overrides this run; omit for standing instructions. Account-wide limit: 30 triggers/min across keys/clients; other accounts do not affect you. On 429 honor Retry-After. run_bulk fans out to 20 workers on a separate window. In-flight worker limit: Free 5/Pro 20/Team 50; excess yields Skipped/ConcurrencyLimit. Language accepts prompt/modelSlug; decision accepts sourceArgs/answers/maxItems instead (wrong kind: 409 not_language_worker/not_decision_worker). Hybrid accepts both: it classifies a bounded window then runs one language agent on selected items, returning one receipt; manual/on-demand only. Classified receipts include coverage and committed wallet cost. Action (modelType none): 400 action_worker_requires_invoke; use worker_tool_call." + RUNTIME_NOTE,
     auth: "manager",
     method: "post",
     schema: {
@@ -903,7 +904,7 @@ const GITHUB_SELECTION = z.object({
 const kitInstallPreview = defineTool({
     name: "kit_install_preview",
     title: "Preview Kit Install",
-    description: "Preview the install form and account readiness; creates nothing. Call before kit_install and collect required answers. {{scope}} requiredInputs: EVERY exact key needs a human-supplied value. memorySetup: only required:true answers are mandatory. modelType language|decision|hybrid|none; decisionNarration explains classification, which acts from the first run without a chosen language model. Answer decisionSetup by key in decisionAnswers: required questions without defaults are mandatory, except appPick can wait for instruction_set. Action: actionSpec lists tools, no model/deployment; actionConnections lists Slack bots to pin via slackConnectionId. workerSlots lists the workers this kit calls (alias, modelType, operations, required): fill them with installed workers in kit_install.workerBindings, or later with worker_bindings_set. Choose ONE member/categorySlot in categoryChoices, preferably connected; connectionProvider requires matching operatorResources.resourceId, preferably hasActiveConnection. apps/appsNeedingConnection predict initial connections; install may proceed blocked, with human setup at connectAppsUrl. githubAccounts.id is connectionId; githubSetup provides requiredScope, discovery tools and explicitSelectionRequired: discover repos/branches, then supply githubSelection selected IDs or accounts:[] to defer. operator identifies target; limits shows currentWorkers/maxWorkers (cap causes 402); kitPageUrl is the human install page. Advisory only: installed readiness is authoritative. kit_get supplies full permissions/instruction. evaluationSpec contains public criteria copied at install; all three quality/learning gates stay off. Review worker_quality_get after install.",
+    description: managerAuthorityPreflight + "Preview the install form and account readiness; creates nothing. Call before kit_install and collect required answers. {{scope}} requiredInputs: EVERY exact key needs a human-supplied value. memorySetup: only required:true answers are mandatory. modelType language|decision|hybrid|none; decisionNarration explains classification, which acts from the first run without a chosen language model. Answer decisionSetup by key in decisionAnswers: required questions without defaults are mandatory, except appPick can wait for instruction_set. Action: actionSpec lists tools, no model/deployment; actionConnections lists Slack bots to pin via slackConnectionId. Slack tools with no usable bot: prompt connection setup, do not submit install. workerSlots lists the workers this kit calls (alias, modelType, operations, required): fill them with installed workers in kit_install.workerBindings, or later with worker_bindings_set. Choose ONE member/categorySlot in categoryChoices, preferably connected; connectionProvider requires matching operatorResources.resourceId, preferably hasActiveConnection. apps/appsNeedingConnection predict initial connections; install may proceed blocked, with human setup at connectAppsUrl. githubAccounts.id is connectionId; githubSetup provides requiredScope, discovery tools and explicitSelectionRequired: discover repos/branches, then supply githubSelection selected IDs or accounts:[] to defer. operator identifies target; limits shows currentWorkers/maxWorkers (cap causes 402); kitPageUrl is the human install page. Advisory only: installed readiness is authoritative. kit_get supplies full permissions/instruction. evaluationSpec contains public criteria copied at install; all three quality/learning gates stay off. Review worker_quality_get after install.",
     auth: "manager",
     method: "get",
     schema: {
@@ -920,9 +921,17 @@ const kitInstallPreview = defineTool({
 const kitInstall = defineTool({
     name: "kit_install",
     title: "Install Kit",
-    description: "Install a kit as a NEW worker. {{scope}} NOT idempotent: every success creates another; never retry success. After timeout, inspect workers_list (readWorkers) first. Preview first: supply every requiredInputs key in inputs (missing/unknown key: 400), required memoryAnswers, decisionAnswers and one categoryChoices entry/slot; connectionProvider also needs resourceId from operatorResources. Install returns no worker API secret. Secret shown ONCE: install.triggers[].signingSecret; give it to the human before discarding. Return workerUrl to the human. readiness ready|blocked includes actionable issues (app_not_connected/candidateProviders); null means the install SUCCEEDED but readiness check failed: worker_get, never reinstall. connectAppsUrl is human setup. 402 limit_exceeded is terminal: upgrade or, with human agreement, worker_delete (permanent; deleteWorkers). Rate: 10 installs/hour/account. Install never runs; without deployment no schedule fires and worker_run returns not_deployed. deploy:true optionally takes deployment(modelSlug from models_list, ceilings) ; missing deployment scope is 403 before creation. Omit deploy to install only, then seek authorized scope review before worker_deploy. Post-install deploy failure still returns 201/deploymentError: worker exists; fix and worker_deploy, never reinstall. Action(modelType none): omit deploy; worker_tools then worker_tool_call. Worker-slot kits (preview lists workerSlots): workerBindings maps each alias to an installed worker, which returns bounded results to the new worker. Install succeeds without bindings, but an unbound required slot reports readiness issue worker_slots_pending and runs are Skipped until worker_bindings_set fills it. Kit criteria copy with all three quality/learning gates off; review worker_quality_get afterwards. Install has no learning-consent options.",
+    description: managerAuthorityPreflight + "Install a kit as a NEW worker. {{scope}} NOT idempotent: every success creates another; never retry success. After timeout, inspect workers_list (readWorkers) first. Preview first: supply every requiredInputs key in inputs (missing/unknown key: 400), required memoryAnswers, decisionAnswers and one categoryChoices entry/slot; connectionProvider also needs resourceId from operatorResources. Install returns no worker API secret. Secret shown ONCE: install.triggers[].signingSecret; give it to the human before discarding. Ordinary missing connections allow creation first. readiness ready|blocked is authoritative. Null readiness means the install SUCCEEDED but its check failed: worker_get, never reinstall. 402 limit_exceeded is terminal: upgrade or, with human agreement, worker_delete (permanent; deleteWorkers). Rate: 10 installs/hour/account. Install never runs; without deployment no schedule fires and worker_run returns not_deployed. deploy:true optionally takes deployment(modelSlug from models_list, ceilings) ; missing deployment scope is 403 before creation. Omit deploy to install only, then seek authorized scope review before worker_deploy. Post-install deploy failure still returns 201/deploymentError: the worker exists but that deployment and its model/ceilings were not saved; fix and worker_deploy, never reinstall. Action(modelType none): omit deploy; worker_tools then worker_tool_call. Worker-slot kits (preview lists workerSlots): workerBindings maps each alias to an installed worker, which returns bounded results to the new worker. Install succeeds without bindings, but an unbound required slot reports readiness issue worker_slots_pending and runs are Skipped until worker_bindings_set fills it. Kit criteria copy with all three quality/learning gates off; review worker_quality_get afterwards. Install has no learning-consent options.",
     auth: "manager",
     method: "post",
+    resultDescription: creationResultGuidance,
+    footer: data => {
+        if (!data || typeof data !== "object" || Array.isArray(data))
+            return undefined;
+        const result = data;
+        return typeof result.workerUrl === "string" && result.workerUrl.trim() && result.error == null
+            ? creationResultGuidance : undefined;
+    },
     schema: {
         slug: KIT_SLUG.describe(KIT_SLUG_HINT),
         operatorId: z.string().uuid().optional().describe("Operator (workspace) to install into. Omit to use the account's default operator."),
@@ -930,7 +939,7 @@ const kitInstall = defineTool({
         avatar: z.string().max(40).optional().describe("Avatar slug for the new worker. Omit for General."),
         timeZoneId: z.string().trim().min(1).max(64).optional().describe("IANA timezone for local dates/reports, set before kit schedules. Ask the worker creator if unknown; never infer from calendars/server clock. Omitted means UTC. Response install.effectiveTimeZoneId confirms the applied zone."),
         slackConnectionId: z.number().int().positive().optional().describe("Action kits: pin a Slack bot from actionConnections in the install preview. A sole usable connection can be selected automatically; choose explicitly when several exist. No model/deployment."),
-        githubSelection: GITHUB_SELECTION.optional().describe("GitHub targets from app_github_accounts/repos/branches (discoverAppResources); preview githubAccounts[].id is connectionId. For specific jobs use selected with 1-500 stable repositoryIds. all includes future granted repos: choose only intentionally. accounts:[] defers setup. Required on GitHub kits for keys with discoverAppResources; legacy keys keep single-account fallback. Discovery/branch inputs grant no access. These owner selections never enter a published kit manifest."),
+        githubSelection: GITHUB_SELECTION.optional().describe("GitHub targets from app_github_accounts/repos/branches (discoverAppResources); preview githubAccounts[].id is connectionId. For specific jobs use selected with 1-500 stable repositoryIds. all includes future granted repos: choose only intentionally. accounts:[] defers setup. Required on GitHub kits for keys with discoverAppResources. Discovery/branch inputs grant no access. These owner selections never enter a published kit manifest."),
         workerBindings: z.record(z.string().regex(/^[a-z][a-z0-9_]{0,19}$/), z.string().uuid()).optional().describe("Map of worker-slot alias (kit_install_preview.workerSlots) to the UUID of the installed worker that fills it. The target must be in the same account and within the caller's current owner/Admin authority and fleet-key selection; its modelType, operations and pinned contracts must match the slot. A binding shares the target's bounded results, never its private receipts. Omit to bind later with worker_bindings_set; an unbound required slot blocks runs. Unknown alias or refused binding: 400."),
         categoryChoices: z.array(z.object({
             categoryCode: z.string().describe("The slot's categoryCode from the preview."),
@@ -1132,7 +1141,7 @@ const DEPLOYMENT_NOTE = " Undeployed workers are configuration only: schedules n
 const listModels = defineTool({
     name: "models_list",
     title: "List Deployable Models",
-    description: "List account-deployable models and prices per million tokens. {{scope}} Use returned slug for deployments; absent models are unavailable by tier/provider, never guess another slug (400). Rows: displayName/provider, inputUsdPerMTok/outputUsdPerMTok/cachedInputUsdPerMTok/cacheWriteInputUsdPerMTok, contextWindowK/minTier/recommended and reasoning controls. thinking accepts reasoningStyle budget -> STRING token count within thinkingBudgetMin/Max; effort -> reasoningEffortOptions; none -> default|off. Wrong kind: 400 invalid_thinking. kitSlug marks the kit recommendation; omitted marks none. byokProviders lists account-key providers (model_keys_list): model usage bills that key plus platform fee. decisionProfiles separately lists enabled classifiers/prices/capabilities; profileId is decisionProfileId on creation/deploy/update/run/run_bulk or a kit default. Language/hybrid use language models; decision uses no modelSlug; Action(modelType none) uses neither list." + RUNTIME_NOTE,
+    description: managerAuthorityPreflight + "List account-deployable models and prices per million tokens. {{scope}} Use returned slug for deployments; absent models are unavailable by tier/provider, never guess another slug (400). Rows: displayName/provider, inputUsdPerMTok/outputUsdPerMTok/cachedInputUsdPerMTok/cacheWriteInputUsdPerMTok, contextWindowK/minTier/recommended and reasoning controls. thinking accepts reasoningStyle budget -> STRING token count within thinkingBudgetMin/Max; effort -> reasoningEffortOptions; none -> default|off. Wrong kind: 400 invalid_thinking. kitSlug marks the kit recommendation; omitted marks none. byokProviders lists account-key providers (model_keys_list): model usage bills that key plus platform fee. decisionProfiles separately lists enabled classifiers/prices/capabilities; profileId is decisionProfileId on creation/deploy/update/run/run_bulk or a kit default. Language/hybrid use language models; decision uses no modelSlug; Action(modelType none) uses neither list." + RUNTIME_NOTE,
     auth: "manager",
     method: "get",
     schema: {
@@ -1167,7 +1176,7 @@ const getDeployment = defineTool({
 const deployWorker = defineTool({
     name: "worker_deploy",
     title: "Deploy Worker",
-    description: "Deploy for hosted runs and schedules; kit_install(deploy:true) combines install/deploy. {{scope}} All deployment options are optional: defaults use the kit's recommended model and platform ceilings. 400 model_required: choose models_list. Fix refusals: 422 instruction_required (add instruction), 422 apps_not_connected (connect named apps or remove grants), 402 wallet_required (human payment required; requestWalletTopUp permits wallet_checkout_create), 402 hosted_worker_limit, 409 already_deployed (deployment_update), 400 invalid_model/model_tier_gated (choose an enabled model within tier), invalid_thinking (model's reasoning vocabulary), invalid_caps (day cap below run cap). Decision needs neither model nor instruction; modelSlug/thinking are refused with invalid_model/invalid_thinking. decision_setup_pending: read instruction_get, optionsFor for live appPick choices, then instruction_set. Action workers return 400 action_worker_requires_invoke; use worker_tool_call. Success warnings[] do not block: ip_rules_enforced warns IP rules will reject hosted platform egress. Without deployment, schedules never fire and worker_run returns 409 not_deployed." + RUNTIME_NOTE + NEW_SCOPE_NOTE,
+    description: managerAuthorityPreflight + "Deploy for hosted runs and schedules; kit_install(deploy:true) combines install/deploy. Deployment does not request a manual run. Failed creation of a deployment saves none of its model/ceilings; the worker remains. {{scope}} All deployment options are optional: defaults use the kit's recommended model and platform ceilings. 400 model_required: choose models_list. Fix refusals: 422 instruction_required (add instruction), 422 apps_not_connected (connect named apps or remove grants), 402 wallet_required (human payment required; requestWalletTopUp permits wallet_checkout_create), 402 hosted_worker_limit, 409 already_deployed (deployment_update), 400 invalid_model/model_tier_gated (choose an enabled model within tier), invalid_thinking (model's reasoning vocabulary), invalid_caps (day cap below run cap). Decision needs neither model nor instruction; modelSlug/thinking are refused with invalid_model/invalid_thinking. decision_setup_pending: read instruction_get, optionsFor for live appPick choices, then instruction_set. Action workers return 400 action_worker_requires_invoke; use worker_tool_call. Success warnings[] do not block: ip_rules_enforced warns IP rules will reject hosted platform egress. Without deployment, schedules never fire and worker_run returns 409 not_deployed." + RUNTIME_NOTE + NEW_SCOPE_NOTE,
     auth: "manager",
     method: "post",
     schema: {
@@ -1193,7 +1202,7 @@ const deployWorker = defineTool({
 const updateDeployment = defineTool({
     name: "deployment_update",
     title: "Update Deployment",
-    description: "Partially update, pause or resume a deployment; omitted fields stay unchanged. {{scope}} pause stops schedules/triggers but retains model/ceilings; prefer it before worker_undeploy for temporary stops. resume cannot lift Suspended status:contact support. Changing modelSlug without thinking keeps a valid reasoning setting, otherwise resets to default with thinking_reset warning. Decision rejects modelSlug/thinking (400 invalid_model/invalid_thinking). A reachable worker without deployment needs worker_deploy;404 may also mean outside key reach. Action workers are never deployed." + RUNTIME_NOTE + NEW_SCOPE_NOTE,
+    description: managerAuthorityPreflight + "Partially update, pause or resume a deployment; omitted fields stay unchanged. {{scope}} pause stops schedules/triggers but retains model/ceilings; prefer it before worker_undeploy for temporary stops. resume cannot lift Suspended status:contact support. Changing modelSlug without thinking keeps a valid reasoning setting, otherwise resets to default with thinking_reset warning. Decision rejects modelSlug/thinking (400 invalid_model/invalid_thinking). A reachable worker without deployment needs worker_deploy;404 may also mean outside key reach. Action workers are never deployed." + RUNTIME_NOTE + NEW_SCOPE_NOTE,
     auth: "manager",
     method: "patch",
     schema: {
@@ -1251,7 +1260,7 @@ const getWorkerPermissions = defineTool({
 const setWorkerPermissions = defineTool({
     name: "worker_permissions_set",
     title: "Set Worker Permissions",
-    description: "Replace what the worker may touch, in the shape worker_permissions_get returns: apps is the whole app set, so an app left out is switched OFF. {{scope}} Account Admin only. An omitted axis keeps the worker's last saved value, so send every axis you mean. The stance changes only when sent: a deny-by-default app switched on here reads nothing until the owner writes rules or you send allowAll:true, and an existing allowAll is never flipped by omission. Rules, identities and MCP tool bindings stay on the dashboard. A scalar left out is unchanged; -1 clears a timeframe. 400 names the refusal: an Action worker, an unknown app or key, a Member-owned worker given an unsupported app, or a classifier losing a tool. Returns the effective permissions; confirm with the human before widening access." + NEW_SCOPE_NOTE,
+    description: "Replace what the worker may touch, in the shape worker_permissions_get returns: apps is the whole native app set, so an app left out is switched OFF. {{scope}} Account Admin only. An omitted axis keeps its saved value; send every intended axis. The stance changes only when sent: a deny-by-default app reads nothing until owner rules or allowAll:true; existing allowAll is never flipped by omission. Rules, identities and MCP tool bindings stay on the dashboard; private API bindings do too. Never send mcp:<slug> or invent its readOperations/writeEnabled here. A scalar left out is unchanged; -1 clears a timeframe. 400 names refusals: Action worker, unknown app/key, unsupported Member app, or classifier losing a tool. Returns the effective permissions; confirm with the human before widening access." + NEW_SCOPE_NOTE,
     auth: "manager",
     method: "put",
     schema: {
@@ -1317,8 +1326,8 @@ const setWorkerBindings = defineTool({
 // much as the wire: read the guide and the vocabulary on the Directory server,
 // validate, publish private, install.
 const KIT_REF = z.string().min(1).max(120);
-const KIT_REF_HINT = "Kit slug from my_kits_list/kit_publish; legacy numeric id also accepted. 404: nonexistent or owned by another account (indistinguishable).";
-const AUTHORING_FLOW_NOTE = " Authoring: kit_authoring_guide (index, schema, rules), kit_vocabulary, then kit_validate the exact publish body. Publish PRIVATE and kit_install; prove a run (Action: tool call), then promote with kit_replace(visibility:'public'). Check key_info; never automatically retry a 403.";
+const KIT_REF_HINT = "Kit slug from my_kits_list/kit_publish. 404: nonexistent or owned by another account (indistinguishable).";
+const AUTHORING_FLOW_NOTE = " Custom drafting: use relevant kit_authoring_guide sections and per-app kit_vocabulary; reuse unchanged help. Validate the exact publish body. Publish private, kit_install, then prove a run or Action tool call before later public promotion. Check key_info; never automatically retry a 403.";
 const kitRefParam = KIT_REF.describe(KIT_REF_HINT);
 const kitRefPath = (params, suffix = "") => `${KITS_API}/${encodeURIComponent(String(params.kitRef))}${suffix}`;
 const withoutKitRef = (params) => {
@@ -1341,7 +1350,7 @@ const LISTING_SCHEMA = {
     declaredModelFloor: z.string().max(80).optional().describe("Display-only minimum model (≤80)."),
     modelScores: z.array(z.record(z.unknown())).max(10).optional().describe("≤10 of {model, score 0-100, notes ≤300} — only for models the kit was actually run on."),
 };
-const CONTENT_SCHEMA = z.record(z.unknown()).describe("Full kit content: read kit_authoring_guide(index/schema and relevant model section) plus kit_vocabulary BEFORE writing; kit_validate rejects unknown keys. Language needs instructionContent; decision needs decisionSpec instead, with no prose commands/whenToUse/resources/memorySetup/selfFactsEnabled. Hybrid needs prose and schema-3 decisionSpec/agentAction; routes agent/escalate/none, source maxItems <=50(default20), agentAction.maxItems <=20(default5), server-gated. Action: modelType none, actionSpec schemaVersion1 with 1-64 ref/version tools from action_worker_options; omitted kit spec uses Slack defaults (action_worker_create uses chosen-app defaults). No model/prompts/memory/schedules/triggers/category slots/deployment; omit appCodes/apps, tools derive grants. Invoke via worker_tools/worker_tool_call. Other compartment/cadence fields follow the guide. For non-Action kits, appCodes (safe defaults) and apps (explicit selections) are mutually exclusive; provide at least one of those, categorySlots or workerSlots. workerSlots (max 10) let the worker call other workers: each declares a portable alias, modelType, operations and required, optionally recommendedKit, actionTools (Action targets) or sourceTool/inputFields (typed Decision input); never account IDs, worker UUIDs or keys. Read kit_authoring_guide section workers first; kit_validate returns workerTools, the exact tool names and schemas the slots expose. Installers bind slots explicitly (kit_install.workerBindings); an unbound required slot blocks runs. Kits carry no contact rules: contact allow-all is fixed, not editable. Optional content.evaluationSpec declares public acceptance criteria (including on protected kits); review them with the creator and keep private cases out. Installation copies criteria but never activates worker quality or learning. See schema for deterministic/model checks and current availability.");
+const CONTENT_SCHEMA = z.record(z.unknown()).describe("Use schema/relevant kit_authoring_guide sections and per-app vocabulary for custom content; reuse unchanged reads. kit_validate rejects unknown keys. Language needs instructionContent; decision needs decisionSpec, with no commands/whenToUse/resources/memorySetup/selfFactsEnabled. Hybrid needs prose and schema-3 decisionSpec/agentAction; routes agent/escalate/none, source maxItems <=50(default20), agentAction.maxItems <=20(default5), server-gated. Action requires modelType none and explicit actionSpec schemaVersion1 with 1-64 ref/version tools discovered through action_worker_options. No implicit app or kit tool selection. No model/prompts/memory/schedules/triggers/category slots/deployment; omit appCodes/apps, tools derive grants. Invoke via worker_tools/worker_tool_call. Non-Action: appCodes XOR apps, or categorySlots/workerSlots; Language may set apps:[]. Prefer explicit apps: appCodes defaults may grant writes. Review effectivePermissions; prose never narrows grants. MCP uses mcpServers gatewayId/toolIds, not native apps; private API bindings are separate (guide index). One kit installs one worker. workerSlots (max 10) declare portable alias, modelType, operations, required and optional recommendedKit, actionTools or sourceTool/inputFields; never worker/account IDs or keys. Read workers; kit_validate returns exact workerTools schemas/names. Create children separately, deploy hosted children and bind via kit_install.workerBindings or worker_bindings_set; unbound required slots block runs. recommendedKit installs nothing. Contact allow-all is fixed: kits carry no rules. evaluationSpec holds public acceptance criteria, including on protected kits; review with the creator, keep private cases out. Installation copies criteria but never activates quality/learning. See schema for remaining fields.");
 const getMyPublisher = defineTool({
     name: "publisher_get_mine",
     title: "Get My Publisher",
@@ -1390,7 +1399,7 @@ const validateKit = defineTool({
     name: "kit_validate",
     title: "Validate Kit",
     description: publicKitPublishingPause +
-        "Dry-run the exact kit_publish body; creates nothing. {{scope}} canPublish is the verdict; errors/warnings identify every failing section (publishing stops at the first), lintWarnings are advisory. Includes inferred requiredInputs, appLabels, normalized memorySetup and exact manifestPreview. Validates as PUBLIC even for private bodies, except the public-kit cap follows visibility (private unlimited). Authored content only; sourceWorkerId is 400. For kit_replace, pass kitRef so the 100-public-kit cap and republish rules use that listing. Repeat until canPublish, then publish the identical body." + AUTHORING_FLOW_NOTE,
+        "Dry-run the exact kit_publish body; creates nothing. {{scope}} canPublish checks validity, not whether grants fit the job. errors block; warnings/lintWarnings are advisory. Review effectivePermissions.apps/categorySlots (normalized grants) and defaultedApps; defaults may include writes or extra providers. Includes requiredInputs, appLabels, normalized memorySetup and exact manifestPreview. Validates as PUBLIC even for private bodies, except the public-kit cap follows visibility (private unlimited). Authored content only; sourceWorkerId is 400. For kit_replace pass kitRef for that listing's cap/republish rules. Fix errors and unintended grants, revalidate, then publish the identical body." + AUTHORING_FLOW_NOTE,
     auth: "manager",
     method: "post",
     schema: {
@@ -1545,7 +1554,7 @@ const PROVIDER_HINT = "Case-insensitive provider code from apps_list.apps[].conn
 const listApps = defineTool({
     name: "apps_list",
     title: "List Connected Apps",
-    description: "Inspect operator app connections before install/publish or after app_not_connected. {{scope}} Never returns secrets. apps[] uses kit app codes: connected means ACTIVE connection or platform credential; providers and connect[] explain setup. auth credential -> app_connect with fields{name,required,secret,hint}; oauth -> human at url (Google/Microsoft/GitHub/Reddit/OAuth gateways); platform -> no setup; admin -> connected for everyone. scope operator|account: account credentials serve all operators; help locates secrets. MCP entries also carry connected per gateway. customMcp lists PUBLISHED platform/own MCP apps; add unsupported apps via mcp_server_create. connections[]: provider/id (app_disconnect.connectionId), apps (one Google connection serves email/calendar/drive), name, operatorId(null=account), status(ACTIVE/REQUIRES_REAUTH/EXPIRED/etc), requiresReauth(reconnect rejected credential), deletable(false=dashboard only). operators[] lists active operators/isDefault; operatorId selects another. warnings identifies failed family reads: rows are MISSING, not evidence of absence; retry the read before concluding.",
+    description: managerAuthorityPreflight + "Inspect native/MCP connections before install/publish or after app_not_connected; API apps use api_apps_list. {{scope}} Never returns secrets. apps[] uses kit app codes: connected means ACTIVE connection or platform credential; providers and connect[] explain setup. auth credential -> app_connect with fields{name,required,secret,hint}; oauth -> human at url (Google/Microsoft/GitHub/Reddit/OAuth gateways); platform -> no setup; admin -> connected for everyone. scope operator|account: account credentials serve all operators; help locates secrets. MCP entries also carry connected per gateway. customMcp lists PUBLISHED platform/own MCP apps; mcp_servers_list includes unpublished own servers. Add via mcp_server_create. connections[]: provider/id (app_disconnect.connectionId), apps (one Google connection serves email/calendar/drive), name, operatorId(null=account), status(ACTIVE/REQUIRES_REAUTH/EXPIRED/etc), requiresReauth(reconnect rejected credential), deletable(false=dashboard only). operators[] lists active operators/isDefault; operatorId selects another. warnings identifies failed family reads: rows are MISSING, not evidence of absence; retry the read before concluding.",
     auth: "manager",
     method: "get",
     schema: {
@@ -1557,7 +1566,7 @@ const listApps = defineTool({
 const connectApp = defineTool({
     name: "app_connect",
     title: "Connect App",
-    description: "Connect or replace an operator app credential. {{scope}} Use apps_list.connect recipes with auth:credential; live-probed before storage, encrypted, never returned. Returns201 connection(id for app_disconnect) and nonfatal warnings, often missing provider scopes. Own MCP credentialScope:account updates the shared credential; add unsupported apps first via mcp_server_create. Errors:400 credential_invalid(fix value,never retry unchanged),502 provider_unavailable(retry SAME request later),400 dashboard_only(human at returned OAuth URL),nothing_to_connect(platform app),managed_by_admin(org-wide platform MCP),404 unknown mcp:<slug>,422 unsupported_provider(environment). Limit: 30 connects/hour/account.",
+    description: managerAuthorityPreflight + "Connect or replace an operator app credential. {{scope}} Use apps_list.connect recipes with auth:credential; live-probed before storage, encrypted, never returned. Returns201 connection(id for app_disconnect) and nonfatal warnings: missing scopes or failed MCP discovery after credential storage. MCP setup includes discovery when needed; use mcp_server_get for saved own-server tools. Own MCP credentialScope:account updates the shared credential. Only new account MCP apps need mcp_server_create; connect existing platform/own apps directly. Errors:400 credential_invalid(fix value,never retry unchanged),502 provider_unavailable(retry SAME request later),400 dashboard_only(human at returned OAuth URL),nothing_to_connect(platform app),managed_by_admin(org-wide platform MCP),404 unknown mcp:<slug>,422 unsupported_provider(environment). Limit: 30 connects/hour/account.",
     auth: "manager",
     method: "post",
     schema: {
@@ -1652,7 +1661,7 @@ const listMcpServers = defineTool({
 const getMcpServer = defineTool({
     name: "mcp_server_get",
     title: "Get MCP Server",
-    description: "One of this account's MCP servers, with every discovered tool (the same shape as a mcp_servers_list entry). 404 not_found = no such server on this account. {{scope}}",
+    description: "Read this account's saved MCP server and every discovered tool (same shape as a mcp_servers_list entry), without contacting upstream or changing tools. 404 not_found = no such server on this account. {{scope}}",
     auth: "manager",
     method: "get",
     schema: {
@@ -1665,7 +1674,7 @@ const getMcpServer = defineTool({
 const createMcpServer = defineTool({
     name: "mcp_server_create",
     title: "Register MCP Server",
-    description: "Register an account MCP app and discover tools. {{scope}} Get an actual public HTTPS MCP endpoint from user/vendor docs; never guess or use a docs URL. authType defaults None; credentials follow its schema: Bearer(token),ApiKeyHeader(header/value),ApiKeyQuery(param/value),Basic(username/password),CustomHeaders(headers), or McpOAuth(human dashboard login). Supplied credentials are live-probed before storage, encrypted, never returned. credentialScope defaults operator (operatorId/default operator); account shares one credential. Omit credential to connect later via app_connect(mcp:<slug>). Returns201 server/discovery(added/changed/removed/unchanged)/next. Unpublished until mcp_server_set_tools enables a tool. 400 credential_invalid:rejected,nothing saved;502 provider_unavailable:check endpoint/retry later,nothing saved;422 invalid_url:requires public HTTPS;400 invalid_request:names enum errors or the 25-server cap. Disclose that upstreamUrl becomes public if a bound kit publishes. Limit: 20 registrations/hour/account.",
+    description: "Register an account MCP app. First check apps_list and mcp_servers_list; reuse a native or MCP app that covers the job. Initial discovery is included when credentials are available or authType is None. Use returned server.tools and next; successful discovery needs no second refresh. {{scope}} Get an actual public HTTPS MCP endpoint from user/vendor docs; never guess or use a docs URL. authType defaults None; credentials follow its schema: Bearer(token),ApiKeyHeader(header/value),ApiKeyQuery(param/value),Basic(username/password),CustomHeaders(headers), or McpOAuth(human dashboard login). Supplied credentials are live-probed before storage, encrypted, never returned. credentialScope defaults operator (operatorId/default operator); account shares one credential. Omit credential to connect later via app_connect(mcp:<slug>). Returns201 server/discovery(added/changed/removed/unchanged)/next. Unpublished until mcp_server_set_tools enables a tool. 400 credential_invalid:rejected,nothing saved;502 provider_unavailable:check endpoint/retry later,nothing saved;422 invalid_url:requires public HTTPS;400 invalid_request:names enum errors or the 25-server cap. Disclose that upstreamUrl becomes public if a bound kit publishes. Limit: 20 registrations/hour/account.",
     auth: "manager",
     method: "post",
     schema: {
@@ -1707,8 +1716,8 @@ const createMcpServer = defineTool({
 });
 const discoverMcpServer = defineTool({
     name: "mcp_server_discover",
-    title: "Discover MCP Server Tools",
-    description: "Rediscover tools using STORED credentials: account-shared or selected/default operator. {{scope}} New tools start withheld; changed tools disable until mcp_server_set_tools re-enables; vanished tools are removed. Returns server/discovery changes/next. 422 not_connected:app_connect(mcp:<slug>) or dashboard for McpOAuth, per message. 502 provider_unavailable:retry later, or reconnect revoked credentials. Limit: 60/hour/account.",
+    title: "Refresh MCP Server Tools",
+    description: "Refresh from upstream and CHANGE the saved tool catalog; use mcp_server_get or mcp_servers_list for a saved read. {{scope}} Creator or account Admin only. Uses STORED credentials: account-shared or selected/default operator. New tools start withheld; changed tools disable until mcp_server_set_tools re-enables; vanished tools are removed. Returns server/discovery changes/next. 422 not_connected:app_connect(mcp:<slug>) or dashboard for McpOAuth, per message. 502 provider_unavailable:retry later, or reconnect revoked credentials. Limit: 60/hour/account.",
     auth: "manager",
     method: "post",
     schema: {
@@ -1750,6 +1759,7 @@ const deleteMcpServer = defineTool({
 export const manageDescriptors = [
     ...apiAppDescriptors,
     ...qualityDescriptors,
+    ...knowledgeDescriptors,
     ...appDiscoveryDescriptors,
     ...onboardingDescriptors,
     ...supportDescriptors,