@anchrd/intel-contract 0.13.0 → 0.15.0

package/dist/contract/table.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId } from "./contract.js";
+import { Node, NodeVersion } from "./node.js";
+const distinctPositions = { error: "Row positions must be distinct" };
+// A table is CSV, and CSV is the whole format: it is what is stored, what is downloaded and what a
+// machine reads. There is no second representation to keep in step with it (#40).
+export const TableMediaType = "text/csv";
+// A column name is the contract between the table and everyone who appends to it, so it is trimmed,
+// non-empty and bounded like a title. Cells are not: a cell is text, and text is what CSV carries.
+export const TableColumn = z.string().trim().min(1).max(120);
+export const TableCell = z.string().max(4_000);
+export const TableRow = z.array(TableCell).min(1).max(64);
+// Writing the header, once. The columns are the contract (#40's comment), which is why this refuses
+// on a table that already has one: changing the header would silently reinterpret every row that
+// was appended under the old one.
+export const DefineTableInput = z.strictObject({
+    nodeId: IntelId.describe("Table node whose header is being written. It must not have one yet."),
+    columns: z
+        .array(TableColumn)
+        .describe("The column names, in order. They are the contract every later append is checked against, which is why this refuses on a table that already has a header — changing it would silently reinterpret the stored rows. Use node_table_update for that.")
+        .min(1)
+        .max(64)
+        .refine((columns) => new Set(columns.map((column) => column.toLowerCase())).size === columns.length, { error: "Column names must be distinct" }),
+    idempotencyKey: IdempotencyKey,
+});
+// ⚠️ No `baseVersionId`, and that absence is the feature. A document replaces its content and needs
+// to know which content it replaces; an append adds to the end and cannot collide with a second
+// append, so demanding a base version would invent a conflict that does not exist and force the
+// caller to read the whole table first — the exact cost #40 exists to remove.
+export const AppendTableRowsInput = z.strictObject({
+    nodeId: IntelId.describe("Table node to append to. It must already have a header."),
+    rows: z
+        .array(TableRow)
+        .min(1)
+        .max(1_000)
+        .describe("Rows to add at the end, each an array of cell strings in the header's order. No base version is needed: appending collides with nothing, so the table does not have to be read first."),
+    idempotencyKey: IdempotencyKey,
+});
+export const GetTableInput = z.strictObject({
+    nodeId: IntelId.describe("Table node to read as a grid: header and every row."),
+});
+export const AppendTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    appended: z.number().int().positive(),
+});
+// A row's address is its position among the table's current rows, counted from zero and without the
+// header. Deliberately not an ID: rows carry no identity of their own (#135, and the same decision
+// the grid documents), so every mutation instead pins the state its positions refer to.
+export const TableRowPosition = z.number().int().nonnegative();
+// Replacing rows in place (#135). `baseVersionId` is the version the caller read the positions
+// from — required, never nullable, because a position into a table one has not read is a guess.
+// A table that moved on since answers `version_conflict` rather than editing the wrong rows; that
+// is the same optimistic concurrency the document save uses, and the deliberate opposite of
+// `append`, which needs no base because it collides with nothing.
+export const UpdateTableRowsInput = z.strictObject({
+    nodeId: IntelId.describe("Table node to change rows in."),
+    baseVersionId: IntelId.describe("The `versionId` from the node_table_get whose rows these positions were counted in. Required and never null: a position into a table nobody has read is a guess. If the table has moved on since, the call is refused rather than editing the wrong rows."),
+    updates: z
+        .array(z.strictObject({
+        position: TableRowPosition.describe("Zero-based position of the row to replace, counting data rows and not the header."),
+        row: TableRow.describe("The complete replacement row, as cell strings in the header's order."),
+    }))
+        .describe("Which rows to replace and with what. `position` is zero-based and counts data rows, not the header; `row` is the complete replacement, not a patch.")
+        .min(1)
+        .max(1_000)
+        .refine((updates) => new Set(updates.map((update) => update.position)).size === updates.length, distinctPositions),
+    idempotencyKey: IdempotencyKey,
+});
+export const UpdateTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    updated: z.number().int().positive(),
+});
+export const DeleteTableRowsInput = z.strictObject({
+    nodeId: IntelId.describe("Table node to remove rows from."),
+    baseVersionId: IntelId.describe("The `versionId` from the node_table_get these positions were counted in. A table that has moved on since is refused rather than losing the wrong rows."),
+    positions: z
+        .array(TableRowPosition)
+        .describe("Zero-based positions of the data rows to remove. All of them go in one call; the positions are read against the base version, so they do not shift while it runs.")
+        .min(1)
+        .max(1_000)
+        .refine((positions) => new Set(positions).size === positions.length, distinctPositions),
+    idempotencyKey: IdempotencyKey,
+});
+export const DeleteTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    deleted: z.number().int().positive(),
+});
+// One entry per column the table will have afterwards, in order. `source` names the current column
+// whose cells fill it; `null` adds an empty column, and a current column no entry names is removed
+// together with its cells. Renaming is naming a source under a new name.
+export const RedefineTableColumn = z.strictObject({
+    name: TableColumn.describe("What the column is called afterwards."),
+    source: TableColumn.nullable()
+        .default(null)
+        .describe("The current column whose cells fill it, by its current name, or `null` for a new empty column."),
+});
+// Changing the header of a table that has one (#135). The mapping is explicit because it is the
+// whole difference to the blind re-definition `defineTable` keeps refusing: without it a new header
+// would silently reinterpret every stored row under names nobody matched to the old ones.
+export const RedefineTableInput = z.strictObject({
+    nodeId: IntelId.describe("Table node whose header is being changed."),
+    baseVersionId: IntelId.describe("The `versionId` from the node_table_get this mapping was written against. A table that has moved on since is refused."),
+    columns: z
+        .array(RedefineTableColumn)
+        .describe("The complete new header, in order. Each entry names the current column whose cells fill it, or `null` for a new empty one; a current column that no entry names is removed with its cells. Renaming is naming a source under a new name. The mapping is explicit on purpose — a new header without one would reinterpret every stored row.")
+        .min(1)
+        .max(64)
+        .refine((columns) => new Set(columns.map((column) => column.name.toLowerCase())).size === columns.length, { error: "Column names must be distinct" })
+        .refine((columns) => {
+        const sources = columns.map((column) => column.source).filter((source) => source !== null);
+        return new Set(sources).size === sources.length;
+    }, { error: "A current column can fill only one new column" }),
+    idempotencyKey: IdempotencyKey,
+});

package/dist/contract/tool.d.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+/**
+ * One MCP server as the portal names it. The handle is what the portal puts in front of every tool
+ * that server offers (`notion_notion-search` belongs to `notion`), and it is the only identifier
+ * Intel can both store and recognise again in a live `tools/list`.
+ *
+ * ⚠️ A handle is never invented from a tool name. Which servers exist is the portal's answer
+ * (`portal_list_servers`), and the prefix is only used to attribute a tool to a server that answer
+ * already named — see `packages/api/src/tools/tool-servers` for why splitting on the underscore
+ * alone would be ambiguous.
+ */
+export declare const ToolServerHandle: z.ZodString;
+export type ToolServerHandle = z.infer<typeof ToolServerHandle>;
+export declare const ToolSourceUrl: z.ZodURL;
+export declare const ToolName: z.ZodString;
+export declare const ToolAnnotations: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+    destructiveHint: z.ZodOptional<z.ZodBoolean>;
+    idempotentHint: z.ZodOptional<z.ZodBoolean>;
+    openWorldHint: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ToolAnnotations = z.infer<typeof ToolAnnotations>;
+export declare const ToolCapability: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    annotations: z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+        destructiveHint: z.ZodOptional<z.ZodBoolean>;
+        idempotentHint: z.ZodOptional<z.ZodBoolean>;
+        openWorldHint: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    fingerprint: z.ZodString;
+}, z.core.$strict>;
+export type ToolCapability = z.infer<typeof ToolCapability>;
+export declare const ToolCatalog: z.ZodObject<{
+    portalConnected: z.ZodBoolean;
+    items: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodNullable<z.ZodString>;
+        description: z.ZodNullable<z.ZodString>;
+        inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        outputSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        annotations: z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+            destructiveHint: z.ZodOptional<z.ZodBoolean>;
+            idempotentHint: z.ZodOptional<z.ZodBoolean>;
+            openWorldHint: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        fingerprint: z.ZodString;
+    }, z.core.$strict>>;
+    reached: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ToolCatalog = z.infer<typeof ToolCatalog>;
+/**
+ * One MCP server the asking user reaches right now, as the portal itself names it (D30).
+ *
+ * ⚠️ `toolCount` is a fact about this moment and this user, not a size. It exists so a picker can
+ * say "9 tools" instead of showing a handle alone, and it must never be read as what an agent will
+ * get: the delegated run asks the portal again, with the delegator's token.
+ */
+export declare const ToolServer: z.ZodObject<{
+    handle: z.ZodString;
+    name: z.ZodString;
+    toolCount: z.ZodNumber;
+}, z.core.$strict>;
+export type ToolServer = z.infer<typeof ToolServer>;
+export declare const ToolServerCatalog: z.ZodObject<{
+    portalConnected: z.ZodBoolean;
+    items: z.ZodArray<z.ZodObject<{
+        handle: z.ZodString;
+        name: z.ZodString;
+        toolCount: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ToolServerCatalog = z.infer<typeof ToolServerCatalog>;
+/**
+ * Which of the named servers a tool belongs to, or `null` for none of them.
+ *
+ * ⚠️ THE TRAP: a tool name does not say where its server name ends.
+ *
+ * The portal writes `<server>_<tool>`, and both halves may contain underscores — `intel_flow_get`
+ * reads equally well as server `intel` with tool `flow_get` and as a server called `intel_flow`
+ * with tool `get`. Splitting on the first underscore is therefore a guess that is wrong the day
+ * somebody adds a server whose name contains one, and on the API side being wrong means an agent
+ * delegated server A quietly reaching server B.
+ *
+ * So the prefix is never split. It is only ever MATCHED against handles the portal itself named,
+ * and the longest match wins: with `intel` and `intel_flow` both declared, `intel_flow_get` belongs
+ * to `intel_flow`, which is the only reading in which both declarations stay true.
+ *
+ * ⚠️ This lives in the contract because HOW A NAME IS READ is a property of the wire, and both
+ * surfaces read the same wire: `packages/api` cuts a delegation with it, `packages/ui` groups the
+ * tools screen with it (#212). A second implementation in the browser would be the third answer to
+ * one question — the underscore rule has already been answered differently in two places once
+ * (#106, #107), and the copies disagreed. What deliberately stays OUT of here is everything about
+ * reach: which handles are declared, which are enabled, which may be delegated and which one owns
+ * the portal's own management tools are decisions with consequences, and they belong to
+ * `packages/api/src/tools/tool-servers`. This function only reads a name.
+ */
+export declare function serverOf(toolName: string, handles: Iterable<string>): string | null;
+export declare const TestToolInput: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type TestToolInput = z.infer<typeof TestToolInput>;
+export declare const ExecuteToolInput: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ExecuteToolInput = z.infer<typeof ExecuteToolInput>;
+export declare const ToolTestResult: z.ZodObject<{
+    isError: z.ZodBoolean;
+    content: z.ZodArray<z.ZodUnknown>;
+    structuredContent: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+export type ToolTestResult = z.infer<typeof ToolTestResult>;

package/dist/contract/tool.js

@@ -0,0 +1,172 @@
+import { z } from "zod";
+function normalizedHostname(url) {
+    return url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+}
+function isPrivateIpv4(hostname) {
+    const parts = hostname.split(".").map(Number);
+    if (parts.length !== 4 ||
+        parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+        return false;
+    }
+    const [first = 0, second = 0] = parts;
+    return (first === 0 ||
+        first === 10 ||
+        first === 127 ||
+        (first === 100 && second >= 64 && second <= 127) ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168) ||
+        (first === 198 && (second === 18 || second === 19)) ||
+        first >= 224);
+}
+function isPublicToolHost(url) {
+    const hostname = normalizedHostname(url);
+    if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1") {
+        return url.protocol === "http:";
+    }
+    if (!hostname.includes(".") ||
+        hostname.endsWith(".local") ||
+        hostname.endsWith(".localhost") ||
+        hostname.endsWith(".internal") ||
+        isPrivateIpv4(hostname) ||
+        hostname.includes(":")) {
+        return false;
+    }
+    return url.protocol === "https:";
+}
+/**
+ * One MCP server as the portal names it. The handle is what the portal puts in front of every tool
+ * that server offers (`notion_notion-search` belongs to `notion`), and it is the only identifier
+ * Intel can both store and recognise again in a live `tools/list`.
+ *
+ * ⚠️ A handle is never invented from a tool name. Which servers exist is the portal's answer
+ * (`portal_list_servers`), and the prefix is only used to attribute a tool to a server that answer
+ * already named — see `packages/api/src/tools/tool-servers` for why splitting on the underscore
+ * alone would be ambiguous.
+ */
+export const ToolServerHandle = z
+    .string()
+    .trim()
+    .min(1)
+    .max(120)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "A server handle is the portal's own identifier");
+export const ToolSourceUrl = z.url().refine((value) => {
+    try {
+        const url = new URL(value);
+        return !url.username && !url.password && isPublicToolHost(url);
+    }
+    catch {
+        return false;
+    }
+}, "The portal must use an approved public HTTPS host without embedded credentials");
+// The portal namespaces every upstream tool, so the name alone identifies the target server. The
+// portal is still the one that resolves it and attaches the credentials — Intel never holds an
+// upstream credential. Since D30 Intel does read the namespace for one purpose: attributing a tool
+// to a server the portal's own `portal_list_servers` already named, so a delegation can be cut to
+// whole servers. That is attribution, not routing.
+export const ToolName = z.string().min(1).max(240);
+export const ToolAnnotations = z.strictObject({
+    title: z.string().max(240).optional(),
+    readOnlyHint: z.boolean().optional(),
+    destructiveHint: z.boolean().optional(),
+    idempotentHint: z.boolean().optional(),
+    openWorldHint: z.boolean().optional(),
+});
+export const ToolCapability = z.strictObject({
+    name: ToolName,
+    title: z.string().max(240).nullable(),
+    description: z.string().max(10_000).nullable(),
+    inputSchema: z.record(z.string(), z.unknown()),
+    outputSchema: z.record(z.string(), z.unknown()).nullable(),
+    annotations: ToolAnnotations,
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+});
+// The catalog reflects one live tools/list for the requesting user. It is never stored as a
+// permission mirror, so there is no per-source state and no Intel-owned connection status.
+export const ToolCatalog = z.strictObject({
+    portalConnected: z.boolean(),
+    items: z.array(ToolCapability),
+    /**
+     * Which delegated servers actually contributed a tool to this catalog (#289).
+     *
+     * ⚠️ Present only where the attribution was actually made — a delegated caller whose catalog was
+     * read. It is absent for an ordinary user, and absent as well when the answer comes from one of
+     * the short paths that never reach the portal (nothing delegated, no portal sign-in, connection
+     * dropped). Absent therefore means "not stated", never "nothing arrived"; `[]` is the second one.
+     *
+     * That it is missing rather than empty on those paths is deliberate rather than half-finished:
+     * the attribution already happens for a delegation — `capabilities` has to make it to cut the
+     * list — so naming it costs nothing there, while computing the same thing for an ordinary user
+     * would mean a second portal request per call, for a question their screen does not ask.
+     *
+     * ⚠️ It is the answer to "what arrived", never to "what was granted". A server missing here has
+     * been switched off, revoked, or is failing right now; the delegation in the definition is
+     * unchanged. Reading it the other way round would turn an outage into a permission change.
+     */
+    reached: z.array(ToolServerHandle).optional(),
+});
+/**
+ * One MCP server the asking user reaches right now, as the portal itself names it (D30).
+ *
+ * ⚠️ `toolCount` is a fact about this moment and this user, not a size. It exists so a picker can
+ * say "9 tools" instead of showing a handle alone, and it must never be read as what an agent will
+ * get: the delegated run asks the portal again, with the delegator's token.
+ */
+export const ToolServer = z.strictObject({
+    handle: ToolServerHandle,
+    name: z.string().min(1).max(240),
+    toolCount: z.number().int().min(0),
+});
+// The same live-query rule as the tool catalog, one level up. `portalConnected: false` is the state
+// of somebody who has not signed into the portal yet, and it is not an error.
+export const ToolServerCatalog = z.strictObject({
+    portalConnected: z.boolean(),
+    items: z.array(ToolServer),
+});
+/**
+ * Which of the named servers a tool belongs to, or `null` for none of them.
+ *
+ * ⚠️ THE TRAP: a tool name does not say where its server name ends.
+ *
+ * The portal writes `<server>_<tool>`, and both halves may contain underscores — `intel_flow_get`
+ * reads equally well as server `intel` with tool `flow_get` and as a server called `intel_flow`
+ * with tool `get`. Splitting on the first underscore is therefore a guess that is wrong the day
+ * somebody adds a server whose name contains one, and on the API side being wrong means an agent
+ * delegated server A quietly reaching server B.
+ *
+ * So the prefix is never split. It is only ever MATCHED against handles the portal itself named,
+ * and the longest match wins: with `intel` and `intel_flow` both declared, `intel_flow_get` belongs
+ * to `intel_flow`, which is the only reading in which both declarations stay true.
+ *
+ * ⚠️ This lives in the contract because HOW A NAME IS READ is a property of the wire, and both
+ * surfaces read the same wire: `packages/api` cuts a delegation with it, `packages/ui` groups the
+ * tools screen with it (#212). A second implementation in the browser would be the third answer to
+ * one question — the underscore rule has already been answered differently in two places once
+ * (#106, #107), and the copies disagreed. What deliberately stays OUT of here is everything about
+ * reach: which handles are declared, which are enabled, which may be delegated and which one owns
+ * the portal's own management tools are decisions with consequences, and they belong to
+ * `packages/api/src/tools/tool-servers`. This function only reads a name.
+ */
+export function serverOf(toolName, handles) {
+    let best = null;
+    for (const handle of handles) {
+        if (!toolName.startsWith(`${handle}_`))
+            continue;
+        if (best === null || handle.length > best.length)
+            best = handle;
+    }
+    return best;
+}
+export const TestToolInput = z.strictObject({
+    name: ToolName.describe("The tool's full name as tool_list reported it, including the server handle it is prefixed with. The portal routes on that prefix, so a bare name reaches nothing."),
+    arguments: z
+        .record(z.string(), z.unknown())
+        .default({})
+        .describe("The arguments, shaped by that tool's own inputSchema from tool_list. Validated against it before anything is sent, so a wrong shape is refused here rather than by the far side."),
+});
+export const ExecuteToolInput = TestToolInput;
+export const ToolTestResult = z.strictObject({
+    isError: z.boolean(),
+    content: z.array(z.unknown()),
+    structuredContent: z.unknown().optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -15,6 +15,34 @@
     ".": {
       "types": "./dist/contract/contract.d.ts",
       "default": "./dist/contract/contract.js"
+    },
+    "./bundle": {
+      "types": "./dist/contract/bundle.d.ts",
+      "default": "./dist/contract/bundle.js"
+    },
+    "./flow": {
+      "types": "./dist/contract/flow.d.ts",
+      "default": "./dist/contract/flow.js"
+    },
+    "./flow-run": {
+      "types": "./dist/contract/flow-run.d.ts",
+      "default": "./dist/contract/flow-run.js"
+    },
+    "./node": {
+      "types": "./dist/contract/node.d.ts",
+      "default": "./dist/contract/node.js"
+    },
+    "./share": {
+      "types": "./dist/contract/share.d.ts",
+      "default": "./dist/contract/share.js"
+    },
+    "./table": {
+      "types": "./dist/contract/table.d.ts",
+      "default": "./dist/contract/table.js"
+    },
+    "./tool": {
+      "types": "./dist/contract/tool.d.ts",
+      "default": "./dist/contract/tool.js"
     }
   },
   "files": [