@softov/ahpc 0.1.0 → 0.3.0

package/dist/src/mcp/tools.d.ts

@@ -0,0 +1,68 @@
+import type { HostConnection } from '../ahp/connection.js';
+/** As much of JSON Schema as a tool's arguments need. */
+export interface Schema {
+    type: 'object';
+    properties: Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+        description?: string;
+        items?: {
+            type: string;
+        };
+        additionalProperties?: boolean | {
+            type: string;
+        };
+    }>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+/**
+ * A set of tools a caller has to ask for by name.
+ *
+ * The core table - sessions, turns, attention - is what a server is for and is
+ * always served. These are not: a tool table is read by a model alongside
+ * everything else it was given, and thirty tools is a worse server than twelve
+ * for the thing almost everybody wants. So they are opt-*in*, one group at a
+ * time, and a caller that needs files says so.
+ */
+export type Group = 'resources' | 'terminals' | 'automations' | 'changes';
+/** Every group there is, for `--mcp-tools` to name in its help. */
+export declare const GROUPS: readonly Group[];
+/** One tool, as MCP describes it and as this client runs it. */
+export interface Tool {
+    /** The name a caller uses. MCP has no dots, so these are underscored. */
+    name: string;
+    /**
+     * The group that has to be turned on for this to be served.
+     *
+     * Absent is core: always there, never asked for.
+     */
+    group?: Group;
+    /** A short label, for a client that shows one. */
+    title: string;
+    /** What it does and when to reach for it, written for a model. */
+    description: string;
+    input: Schema;
+    /** Whether it changes anything, which some clients ask a person about. */
+    readOnly: boolean;
+    /**
+     * Do it.
+     *
+     * `report` is where to say what is happening while a long one runs, and is
+     * absent unless the caller asked for progress and the transport can carry
+     * it. A tool that reports nothing is a tool that finishes quickly enough
+     * not to need to.
+     */
+    run(host: HostConnection, input: Record<string, unknown>, report?: (said: string) => void): Promise<unknown>;
+}
+export declare const TOOLS: Tool[];
+/**
+ * One tool by the name a caller used, or nothing.
+ *
+ * Over the whole table, including groups nobody turned on - whether a tool
+ * exists and whether this server serves it are different questions, and
+ * `served` answers the second. Telling somebody the tool is in a group they
+ * did not ask for is a better answer than telling them it does not exist.
+ */
+export declare const named: (name: string) => Tool | undefined;
+/** The tools a server started with these groups serves. */
+export declare const served: (groups?: readonly string[]) => Tool[];