@critical-path/mcp 0.18.1 → 0.19.0

package/dist/skills/catalog.generated.js

@@ -0,0 +1,33 @@
+export const SKILL_CATALOG = [
+    {
+        "name": "analyze-schedule",
+        "description": "Find what drives a project's end date, how much each task can slip and where people are double-booked, then recommend fixes. Use for \"when will we finish?\", \"what is critical?\" or deadline-risk questions.",
+        "content": "---\nname: analyze-schedule\ndescription: Find what drives a project's end date, how much each task can slip and where people are double-booked, then recommend fixes. Use for \"when will we finish?\", \"what is critical?\" or deadline-risk questions.\n---\n\n# Analyze the schedule\n\n## 1. Run the schedule\n\n1. Get the `projectId` (`list_projects`).\n2. Call `calculate_critical_path` with `calendars: \"assignee\"` and `levelResources: true`, so each person works on one task at a time on their own calendar. If the user wants the ideal schedule with unlimited people, call it with no options instead.\n3. If the question spans projects that share people, call `calculate_portfolio_critical_path` with their `projectIds` (and `projectOrder` if the user ranked them) instead.\n4. For in-flight projects, pass `effort: \"remaining\"` so finished hours are not scheduled again.\n\n## 2. Read the result\n\n- `projectEndDate` is the forecast finish. With levelling, compare it with `unleveledProjectEndDate`: the gap is time lost waiting for busy people.\n- `criticalTaskIds` are the tasks with zero slack. Any delay to one of them moves the end date.\n- Each entry in `tasks` has `slackWorkingHours`: how many working hours the task can slip without moving the end. Under about 8 hours is near-critical.\n- `levelingDelayHours` and `waitingOn` show a task that waited for its assignee to finish another task.\n- `overallocations` lists periods where a person (`assigneeId`) or team (`teamId`) is booked above `capacity`; `allocation` 1.5 means 150%.\n\nLook up titles for the task ids you mention with `get_task` or `list_tasks`; report titles, not ids. To see why a critical task cannot start earlier, call `get_task` with `includeDependencies: true`: `dependencies.dependsOn` lists what it waits for and `dependencies.dependents` what waits for it.\n\n## 3. Recommend\n\nRank fixes by how much they pull the end date in:\n\n1. **Unblock critical tasks.** A critical task with `isBlocked: true` delays everything; say what it waits for.\n2. **Move work off the bottleneck person.** If critical tasks wait on one assignee (`waitingOn`), suggest reassigning a non-critical task of theirs.\n3. **Remove false dependencies.** A critical task waiting on work it does not really need (`dependencies.dependsOn`) can start earlier once the link is removed.\n4. **Split long critical tasks** so parts can run in parallel.\n5. **Cut or defer** tasks feeding late deliverables, if dates are fixed.\n\nShow the recommendation to the user. Change tasks (`update_task`) or dependencies (`add_dependency`, `remove_dependency`) only when they ask, then run the schedule again to show the effect.\n\n## Report format\n\n- Forecast finish date, and against any deadline the user gave.\n- Critical path: task titles in order, with assignee.\n- Top risks: near-critical tasks, blocked critical tasks, over-allocations.\n- Recommended actions, each with its expected effect.\n"
+    },
+    {
+        "name": "investigate-task",
+        "description": "Work out why a specific task is late, stalled or over budget and what it puts at risk. Use when the user asks about one task's status, delay or overrun.",
+        "content": "---\nname: investigate-task\ndescription: Work out why a specific task is late, stalled or over budget and what it puts at risk. Use when the user asks about one task's status, delay or overrun.\n---\n\n# Investigate a task\n\n## 1. Identify the task\n\nIf the user named the task rather than giving its id, find it with `list_tasks` (filter by project, assignee or status) and confirm which one they mean if several match.\n\n## 2. Gather evidence\n\n1. `get_task` with `includeDependencies: true`: status, assignee, estimate, logged hours, due date, `isBlocked` and `blockedReason`, plus the tasks it waits for (`dependencies.dependsOn`, with their status) and the tasks waiting on it (`dependencies.dependents`).\n2. `get_task_metrics`: progress and variance.\n3. `get_task_ladder`: its phase (`macroPhase`) and that phase's health, and its schedule in `standard.cpm` (`isCritical`, `slackWorkingHours`).\n4. `list_comments`: what people said about it, especially recent blockers or decisions.\n\n## 3. Diagnose\n\nCheck these in order and stop at the ones that explain the problem:\n\n| Signal | Meaning |\n| --- | --- |\n| `isBlocked` true, an unfinished task in `dependencies.dependsOn`, or comments mention waiting | Blocked. Name what it waits for and its status; investigate that task the same way if it is late too. |\n| `progressHistory.curveProfile` is `stalled` | No progress recently. Check whether the assignee moved to other work. |\n| `realityDelta.isOverEstimate` true or `evm.costPerformanceIndex` below 0.9 | Taking more effort than estimated. The estimate was too low or scope grew. |\n| `evm.schedulePerformanceIndex` below 0.9 or `realityDelta.isOverdue` | Behind schedule. Give `scheduleVarianceWorkingDays`. |\n| No `estimatedHours` | Metrics cannot be trusted; say so and suggest adding an estimate. |\n| `curveProfile` is `late_rush` | Most progress lands near the deadline; the remaining work may be underestimated. |\n\n## 4. Assess the impact\n\n- If the task is critical (`standard.cpm.isCritical`), every day it slips moves the project end. Say so plainly.\n- List the tasks waiting on it (`dependencies.dependents`, by title); they slip with it.\n- Otherwise, report how much slack it has left before it becomes critical.\n- Name the phase or deliverable it endangers.\n\n## 5. Answer\n\nLead with a one-sentence diagnosis, then the evidence (with numbers), the impact, and one to three concrete next steps (unblock, re-estimate, reassign, split). Change the task with `update_task` or record the finding with `add_comment` only if the user asks.\n"
+    },
+    {
+        "name": "plan-capacity",
+        "description": "Check who is overloaded or idle over a time window and rebalance assignments. Use for capacity planning, workload balancing or \"can we take on more work?\" questions.",
+        "content": "---\nname: plan-capacity\ndescription: Check who is overloaded or idle over a time window and rebalance assignments. Use for capacity planning, workload balancing or \"can we take on more work?\" questions.\n---\n\n# Plan capacity\n\n## 1. Measure the load\n\n1. Decide the window and grain with the user, defaulting to the next 8 weeks by `interval: \"week\"`.\n2. Call `get_workload_distribution` with `groupBy: \"assignee\"`, `metric: \"remaining\"`, `startDate` and `endDate` (YYYY-MM-DD). Pass `projectId` for one project, or omit it for the whole workspace (people usually work across projects). Use `groupBy: \"team\"` for team-level questions.\n3. If people do not work 40-hour weeks, pass `defaultWeeklyCapacityHours`.\n\n## 2. Read it\n\n- `seriesKeys` are the people (or teams); `seriesLabels` maps each to a display name.\n- In each bucket, `values[key]` is booked hours and `capacity[key]` is available hours. Load = values / capacity.\n- `utilizationRatio` above 1 is overloaded for the bucket as a whole; check each person too, since one overloaded person hides inside a team average.\n- Treat above 1.0 as overloaded, 0.8-1.0 as full, below 0.5 as spare capacity.\n- Work with no assignee (or team) appears under the key `unassigned`; it is demand nobody has picked up.\n\n## 3. Find what to move\n\n1. For each overloaded person and week, call `list_tasks` with their `assigneeId` to see the tasks behind it.\n2. Call `calculate_critical_path` (with `calendars: \"assignee\"`) for the affected project to learn which of those tasks are critical. Move non-critical tasks first; they have slack.\n3. Match each task with a person who has spare capacity in that window.\n\n## 4. Propose\n\nGive a table: task, from, to, hours moved, effect on both people's load. Note the remaining overload if it cannot be fully resolved, and the options (push dates, add people, cut scope).\n\nApply reassignments with `update_task` (`assigneeId`) only after the user approves, and record each one with `add_comment`.\n"
+    },
+    {
+        "name": "plan-project",
+        "description": "Turn a goal, brief or feature list into a Critical Path project with deliverables, estimated and prioritized tasks, and the dependencies between them. Use when the user asks to plan, scope or break down work.",
+        "content": "---\nname: plan-project\ndescription: Turn a goal, brief or feature list into a Critical Path project with deliverables, estimated and prioritized tasks, and the dependencies between them. Use when the user asks to plan, scope or break down work.\n---\n\n# Plan a project\n\nTurn a goal into deliverables (dated outcomes), tasks (estimated units of work) and dependencies (which task waits for which) the scheduler can use.\n\n## 1. Find or create the project\n\n1. Call `list_projects`. If a project already matches the goal, use it and read it with `get_project` to learn its workflow status keys and custom fields.\n2. Only if none fits, and the user wants a new one, call `create_project` with a `name` and a short `key`.\n3. Call `list_tasks` with the `projectId` and `list_deliverables` to see what already exists. Do not recreate it.\n\n## 2. Draft the plan before writing anything\n\nBreak the goal down in your reply first and show it to the user:\n\n- **Deliverables**: 2-6 outcomes someone could accept or reject, each with a due date if the user gave one.\n- **Tasks** under each deliverable. Each task:\n  - starts with a verb and is small enough for one person (about 2-24 hours);\n  - has `estimatedHours` (effort, not elapsed time);\n  - has a `priority`: `urgent` only for work that blocks others now, `high` for the critical outcome, `medium` by default, `low` for nice-to-haves;\n  - lists the tasks it must wait for (its dependencies). Only add a dependency when the work truly cannot start earlier; every extra one lengthens the schedule.\n- Note anything you assumed (team size, dates, scope) as a question.\n\nAsk the user to confirm or adjust before creating anything. A plan is cheap to change in chat and tedious to change once created.\n\n## 3. Create it\n\n1. Create tasks with `create_task` (`projectId`, `title`, `description` with acceptance criteria, `estimatedHours`, `priority`, `assigneeId` if known). Leave `status` out so tasks start in the workflow's default status.\n2. Create each deliverable with `create_deliverable`, passing the ids of its tasks in `taskIds`.\n3. Add each dependency from your plan with `add_dependency`: `taskId` is the task that waits, `dependsOnTaskId` the task that must finish first. Use the ids `create_task` returned. If one is refused as circular, your plan has a loop: fix the order with the user instead of retrying.\n4. If the project already had tasks, check what they wait for with `get_task` and `includeDependencies: true` before linking new work to them.\n\n## 4. Check the result\n\n1. Call `calculate_critical_path` for the project and report the forecast `projectEndDate` and the `criticalTaskIds` (by title). If every task is critical or the end date looks too early, a dependency is probably missing or reversed.\n2. If the end date misses a deliverable's due date, say so and suggest what to cut, split or reassign. The `analyze-schedule` skill covers this in depth.\n\n## Guardrails\n\n- Never invent user ids for `assigneeId`. Leave tasks unassigned unless the user named the person and you have their id.\n- Keep the plan to what the user asked for; propose extra work as suggestions, not tasks.\n"
+    },
+    {
+        "name": "report-status",
+        "description": "Write a project status report covering progress, phase health, forecast finish, risks and blockers, backed by the schedule and metrics. Use when the user asks how a project is going or wants a status update.",
+        "content": "---\nname: report-status\ndescription: Write a project status report covering progress, phase health, forecast finish, risks and blockers, backed by the schedule and metrics. Use when the user asks how a project is going or wants a status update.\n---\n\n# Report project status\n\n## 1. Collect the facts\n\n1. Get the `projectId` (`list_projects`).\n2. Call `get_timeline_ladder` with `level: \"macro\"`. It gives overall `health`, `overallProgressPercentage`, `projectedFinishDate`, task counts and `phases`, each with its own `health`, `progressPercentage` and `isCritical`.\n3. Call `calculate_critical_path` (with `effort: \"remaining\"`) for the forecast `projectEndDate` and the `criticalTaskIds`.\n4. Call `list_tasks` for blocked and urgent work: once with `priority: \"urgent\"` and scan the results (and the project's tasks) for `isBlocked: true`.\n5. For each phase that is `at_risk`, `blocked` or `overdue`, pick its most important open tasks (critical ones first) and call `get_task_metrics` on up to 5 of them.\n6. Call `list_deliverables` and compare each due date with the forecast.\n\n## 2. Interpret\n\n- Phase `health`: `on_track`, `at_risk`, `blocked`, `overdue` or `completed`.\n- Task `evm`: `schedulePerformanceIndex` (SPI) below 0.9 means behind schedule; `costPerformanceIndex` (CPI) below 0.9 means more hours than the progress justifies.\n- `realityDelta.isOverdue` and `scheduleVarianceWorkingDays` give lateness in working days.\n- `progressHistory.curveProfile`: `stalled` needs attention now; `late_rush` suggests hidden risk near the due date.\n\n## 3. Write the report\n\nKeep it short and lead with the answer.\n\n```\n**Status: <On track | At risk | Off track>**, <progress>% done, forecast finish <date> (<deadline comparison>).\n\n**Phases**\n- <phase>: <health>, <progress>%  <one-line reason if not on track>\n\n**Risks and blockers**\n- <task title> (<assignee>): <what is wrong, with the number>, <what would fix it>\n\n**Deliverables**\n- <title>: due <date>, forecast <on time | late by N days>\n\n**Next steps**\n- <owner>: <action>\n```\n\nUse task titles, not ids. Name a number for every claim (dates, percentages, hours). If data is missing (no estimates, no logged hours), say so: metrics without estimates are not meaningful.\n\nOnly post the report with `add_comment` if the user asks.\n"
+    },
+    {
+        "name": "triage-tasks",
+        "description": "Review new, unprioritized or stale tasks and set priority, estimate, tags and blocked state consistently. Use when the user asks to triage, groom or clean up a backlog.",
+        "content": "---\nname: triage-tasks\ndescription: Review new, unprioritized or stale tasks and set priority, estimate, tags and blocked state consistently. Use when the user asks to triage, groom or clean up a backlog.\n---\n\n# Triage tasks\n\nMake every task in scope actionable: a clear title, a priority, an estimate and an honest blocked state.\n\n## 1. Gather the tasks\n\n1. Get the `projectId` with `list_projects` if you do not have it, then `get_project` to learn the workflow status keys.\n2. Call `list_tasks` with filters that match the request, for example:\n   - untriaged: `priority: \"none\"`;\n   - a backlog: `status` set to the backlog key from the workflow;\n   - one person's work: `assigneeId`.\n   Page with `nextCursor` until it is empty, or stop at a sensible batch (about 25) and say how many remain.\n3. For tasks whose description is thin or which look blocked, read the discussion with `list_comments`.\n\n## 2. Decide, task by task\n\n| Field | Rule |\n| --- | --- |\n| `priority` | `urgent`: blocks other people now or a live problem. `high`: needed for the next deliverable. `medium`: planned work. `low`: nice to have. Reserve `urgent` for a handful of tasks. |\n| `estimatedHours` | Effort in hours. If a task is over about 24 hours, propose splitting it instead of estimating it. |\n| `tags` | Reuse tags already used in the project; do not invent a new scheme. |\n| `isBlocked` / `blockedReason` | Blocked only when work cannot continue; the reason names what it waits for. |\n| title | Starts with a verb and says the outcome. Rewrite only when it is unclear. |\n\nFlag likely duplicates (same outcome, different words) instead of deleting them.\n\n## 3. Propose, then apply\n\n1. Show the user a table: task title, current values, proposed values, one-line reason.\n2. After the user approves (all or some), apply each change with `update_task`, passing only the fields that change.\n3. For any non-obvious change, record why with `add_comment` on the task.\n\n## Guardrails\n\n- Do not change `status` or `assigneeId` during triage unless the user asked for it.\n- Never call `delete_task` during triage. Suggest canceling duplicates and let the user decide.\n"
+    }
+];
+//# sourceMappingURL=catalog.generated.js.map

package/dist/skills/catalog.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.generated.js","sourceRoot":"","sources":["../../src/skills/catalog.generated.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,aAAa,GAAY;IACpC;QACE,MAAM,EAAE,kBAAkB;QAC1B,aAAa,EAAE,kNAAkN;QACjO,SAAS,EAAE,+4FAA+4F;KAC35F;IACD;QACE,MAAM,EAAE,kBAAkB;QAC1B,aAAa,EAAE,0JAA0J;QACzK,SAAS,EAAE,uhFAAuhF;KACniF;IACD;QACE,MAAM,EAAE,eAAe;QACvB,aAAa,EAAE,yKAAyK;QACxL,SAAS,EAAE,o+DAAo+D;KACh/D;IACD;QACE,MAAM,EAAE,cAAc;QACtB,aAAa,EAAE,kNAAkN;QACjO,SAAS,EAAE,gnGAAgnG;KAC5nG;IACD;QACE,MAAM,EAAE,eAAe;QACvB,aAAa,EAAE,iNAAiN;QAChO,SAAS,EAAE,syEAAsyE;KAClzE;IACD;QACE,MAAM,EAAE,cAAc;QACtB,aAAa,EAAE,0KAA0K;QACzL,SAAS,EAAE,8oEAA8oE;KAC1pE;CACF,CAAC"}

package/dist/skills/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A playbook an agent loads for a multi-step job. `content` is the full SKILL.md (Agent Skills
+ * format: YAML frontmatter with `name` and `description`, then markdown steps).
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    content: string;
+}
+/** Skills bundled with this package. Sources live in `skills/<name>/SKILL.md`. */
+export declare const SKILLS: readonly Skill[];
+export declare function getSkill(name: string): Skill | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,eAAO,MAAM,MAAM,EAAE,SAAS,KAAK,EAAkB,CAAC;AAEtD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAExD"}

package/dist/skills/index.js

@@ -0,0 +1,7 @@
+import { SKILL_CATALOG } from './catalog.generated.js';
+/** Skills bundled with this package. Sources live in `skills/<name>/SKILL.md`. */
+export const SKILLS = SKILL_CATALOG;
+export function getSkill(name) {
+    return SKILLS.find((skill) => skill.name === name);
+}
+//# sourceMappingURL=index.js.map

package/dist/skills/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAYvD,kFAAkF;AAClF,MAAM,CAAC,MAAM,MAAM,GAAqB,aAAa,CAAC;AAEtD,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACrD,CAAC"}

package/dist/tools/definitions.d.ts

@@ -2,26 +2,58 @@ import { z } from 'zod';
 import type { CriticalPathEngine } from '@critical-path/core';
 import type { CriticalPathClient } from '@critical-path/client';
 export type BackendContext = CriticalPathEngine | CriticalPathClient;
+/**
+ * Groups of related tools. Hosts expose only the groups an agent needs (`toolsets` option), which
+ * keeps the tool list short and tool choice accurate.
+ */
+export declare const TOOLSETS: {
+    readonly core: "Projects, tasks and task dependencies: find, read, create, update and delete";
+    readonly collaboration: "Deliverables (milestones) and task comments";
+    readonly scheduling: "Critical path, portfolio scheduling and workload/capacity";
+    readonly analytics: "Project status ladder, task metrics, earned value and progress history";
+    readonly guidance: "Skills: step-by-step playbooks for multi-step jobs";
+};
+export type ToolsetName = keyof typeof TOOLSETS;
+/** Standard MCP tool annotations. */
+export interface ToolAnnotations {
+    /** The tool does not change anything. */
+    readOnlyHint: boolean;
+    /** The tool may delete or irreversibly overwrite data; hosts should confirm with the user. */
+    destructiveHint: boolean;
+    /** Calling it again with the same arguments has no further effect. */
+    idempotentHint: boolean;
+    /** The tool reaches systems outside this Critical Path backend. */
+    openWorldHint: boolean;
+}
 export interface ToolDefinition<TParams = any, TResult = any> {
     name: string;
     title: string;
+    /**
+     * What the model reads to choose a tool. Say what question it answers, when to use it, what it
+     * returns, and which sibling tool to use instead (in backticks) when the two could be confused.
+     */
     description: string;
+    toolset: ToolsetName;
     zodSchema: z.ZodObject<any>;
     /** JSON Schema shown to MCP clients. Generated from `zodSchema` by `defineTool`. */
     inputSchema: Record<string, unknown>;
-    annotations?: {
-        readOnlyHint?: boolean;
-        requiresConfirmation?: boolean;
-    };
+    /** Shape of the result. Results are always JSON objects so they can be sent as structured content. */
+    outputZodSchema: z.ZodTypeAny;
+    /** JSON Schema of the result shown to MCP clients. Generated from `outputZodSchema` by `defineTool`. */
+    outputSchema: Record<string, unknown>;
+    annotations: ToolAnnotations;
     execute: (args: TParams, target: BackendContext, ambientContext?: {
         projectId?: string;
     }) => Promise<TResult>;
 }
+type ToolSpec<TParams, TResult> = Omit<ToolDefinition<TParams, TResult>, 'inputSchema' | 'outputSchema' | 'annotations'> & {
+    annotations?: Partial<ToolAnnotations>;
+};
 /**
- * Declares a tool, generating its JSON Schema `inputSchema` from `zodSchema` so the schema the
- * model sees and the one arguments are validated against cannot drift apart.
+ * Declares a tool, generating its JSON Schema `inputSchema` and `outputSchema` from the zod schemas
+ * so the schemas the model sees and the ones values are checked against cannot drift apart.
  */
-export declare function defineTool<TParams = any, TResult = any>(spec: Omit<ToolDefinition<TParams, TResult>, 'inputSchema'>): ToolDefinition<TParams, TResult>;
+export declare function defineTool<TParams = any, TResult = any>(spec: ToolSpec<TParams, TResult>): ToolDefinition<TParams, TResult>;
 export declare class ToolArgumentError extends Error {
     constructor(toolName: string, details: string);
 }
@@ -33,7 +65,9 @@ export declare function parseToolArgs<TParams>(tool: ToolDefinition<TParams>, ar
 export declare function resolveBackend(target: BackendContext): Promise<{
     isEngine: boolean;
 }>;
-export declare const listProjectsTool: ToolDefinition<any, import("@critical-path/core").Project[]>;
+export declare const listProjectsTool: ToolDefinition<any, {
+    projects: import("@critical-path/core").Project[];
+}>;
 export declare const getProjectTool: ToolDefinition<{
     id: string;
 }, any>;
@@ -57,6 +91,7 @@ export declare const listTasksTool: ToolDefinition<{
 }, any>;
 export declare const getTaskTool: ToolDefinition<{
     id: string;
+    includeDependencies?: boolean;
 }, any>;
 export declare const createTaskTool: ToolDefinition<{
     projectId?: string;
@@ -92,6 +127,16 @@ export declare const updateTaskTool: ToolDefinition<{
 export declare const deleteTaskTool: ToolDefinition<{
     id: string;
 }, any>;
+export declare const addDependencyTool: ToolDefinition<{
+    taskId: string;
+    dependsOnTaskId: string;
+    type?: "blocking" | "relates_to";
+}, any>;
+export declare const removeDependencyTool: ToolDefinition<{
+    taskId: string;
+    dependsOnTaskId: string;
+    type?: "blocking" | "relates_to";
+}, any>;
 export declare const listDeliverablesTool: ToolDefinition<{
     projectId?: string;
 }, any>;
@@ -151,6 +196,35 @@ export declare const getWorkloadDistributionTool: ToolDefinition<{
     metric?: "scheduled" | "logged" | "remaining" | "blended";
     defaultWeeklyCapacityHours?: number;
 }, any>;
+export declare const getSkillTool: ToolDefinition<{
+    name?: string;
+}, any>;
 export declare const ALL_TOOLS: ToolDefinition[];
 export declare const TOOL_MAP: Map<string, ToolDefinition<any, any>>;
+export interface ToolSelection {
+    /** Exact tool names to expose. Combined with `toolsets` (a tool in either is exposed). */
+    tools?: string[];
+    /** Tool groups to expose. Without `tools` or `toolsets`, every tool is exposed. */
+    toolsets?: ToolsetName[];
+    /** Expose only tools that change nothing. */
+    readOnly?: boolean;
+}
+/**
+ * Picks the tools a host exposes. Unknown tool or toolset names throw, so a typo cannot silently
+ * leave an agent without the tools it was meant to have. `get_skill` follows the same rules as
+ * other tools: include the `guidance` toolset (or name it) to keep skills reachable.
+ */
+export declare function selectTools(selection?: ToolSelection): ToolDefinition[];
+export declare class ToolNotFoundError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates arguments, runs a tool and returns a JSON-safe object result. A missing record (a
+ * `null` result) becomes an error, and errors carry a hint for what to do next so the agent can
+ * recover on its own.
+ */
+export declare function runTool(tool: ToolDefinition, args: unknown, target: BackendContext, ambientContext?: {
+    projectId?: string;
+}): Promise<Record<string, unknown>>;
+export {};
 //# sourceMappingURL=definitions.d.ts.map

package/dist/tools/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"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"}