@segmentstream/ontology 0.0.0-stage → 0.92.1

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

@@ -0,0 +1,99 @@
+import { Schema } from "effect";
+import type { JsonSchemaObject } from "../../analyze.js";
+import { type PermissionHolder } from "../../permissions.js";
+import { type MemberFileOperation } from "../member-files.js";
+import type { BuiltApi } from "../api.js";
+import type { CallerContext } from "../caller-context.js";
+import { type ConfirmationFacts } from "./confirmation.js";
+import type { PlannedAction, PlannedEntity } from "../plan.js";
+/** How a tool behaves, as MCP's tool annotations say it. */
+export interface McpToolAnnotations {
+    readonly readOnlyHint: boolean;
+    readonly destructiveHint?: boolean;
+    /** Ontology extension: whether the action has an effect without a complete undo. */
+    readonly irreversibleHint?: boolean;
+    readonly idempotentHint?: boolean;
+    /** Whether the tool reaches beyond the ontology: true for actions that call connections. */
+    readonly openWorldHint: boolean;
+}
+/** What a tool runs: a read or an action of an entity, or one of the global tools. */
+export type McpToolTarget = {
+    readonly kind: "find" | "get" | "history";
+    readonly planned: PlannedEntity;
+} | {
+    readonly kind: "action";
+    readonly planned: PlannedEntity;
+    readonly action: PlannedAction;
+} | {
+    readonly kind: "discover";
+} | {
+    readonly kind: "navigation";
+} | {
+    readonly kind: "me";
+} | {
+    readonly kind: "query-metrics";
+} | {
+    readonly kind: "list-metrics" | "get-dimensions" | "get-dimension-values";
+} | {
+    readonly kind: "conversation-search";
+} | {
+    readonly kind: "chat-list" | "chat-history";
+} | {
+    readonly kind: "member-file";
+    readonly operation: MemberFileOperation;
+};
+/** A tool of the ontology's MCP server, derived from the same plan as the HTTP routes. */
+export interface McpTool {
+    readonly _meta?: Readonly<Record<string, unknown>>;
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+    /** The JSON Schema of the tool's `structuredContent`, for the tools that return a known shape. */
+    readonly outputSchema?: JsonSchemaObject;
+    readonly annotations: McpToolAnnotations;
+    /** Every permission a caller needs to see and run the tool; none for the global tools. */
+    readonly permissions: ReadonlyArray<string>;
+    /**
+     * For a tool whose input depends on what the caller may read: the caller's input schema, or
+     * `undefined` when the tool can do nothing for them and is not listed. Calls are checked anyway.
+     */
+    readonly inputSchemaFor?: (caller: PermissionHolder) => JsonSchemaObject | undefined;
+    /** A confirmable action's card facts, listed under its annotations; see `CONFIRMATION_FACTS`. */
+    readonly confirmation?: ConfirmationFacts;
+    /**
+     * For a tool whose description names what the caller may read: the caller's description. The
+     * static `description` then names nothing beyond the tool's own permissions.
+     */
+    readonly descriptionFor?: (caller: PermissionHolder) => string;
+    readonly target: McpToolTarget;
+}
+/** The JSON Schema of what a schema encodes to: the shape the service sends. */
+export declare function encodedJsonSchema(schema: Schema.Top): JsonSchemaObject;
+/**
+ * The argument an action that consumes or stages an upload takes beside its input: the idempotency key the
+ * runtime requires of it, and the create intent the upload was begun with. The service removes it
+ * before the input is validated.
+ */
+export declare const ACTION_OPTIONS_ARGUMENT = "_options";
+/** The `me` tool's marker: tool calls accept the runtime envelope's chat source. */
+export declare const RUNTIME_SOURCE_META = "segmentstream/runtime-source";
+/** The `chat_post_message` tool's marker: the deployment posts exact messages to its chat. */
+export declare const CHAT_POST_META = "segmentstream/chat-post";
+/**
+ * The MCP tools of an ontology: `me`, `discover` when it ranks by meaning, opt-in `navigation`,
+ * and the metric tools when the ontology has metrics,
+ * then for every stored entity `find`, `get`,
+ * `history` and a tool per generated and authored action. Entities with a warehouse source have none,
+ * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
+ * `check` already refuses.
+ */
+export declare function mcpTools(built: BuiltApi, conversations?: boolean, storage?: {
+    attachments?: boolean;
+    files?: boolean;
+}, navigation?: boolean): ReadonlyArray<McpTool>;
+/**
+ * The tools a caller may see: those whose every permission the caller's roles grant, each with the
+ * caller's input schema.
+ */
+export declare function visibleTools(tools: ReadonlyArray<McpTool>, caller: PermissionHolder, provenance?: CallerContext): ReadonlyArray<McpTool>;