@anchrd/intel 0.59.0

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/intel/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/intel` cuts a delegation with it, `packages/intel/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/intel/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/dist/feed/feed.d.ts

@@ -0,0 +1,2 @@
+import type { FeedDeps, FeedService } from "./feed.types.js";
+export declare function createFeed(deps: FeedDeps): FeedService;

package/dist/feed/feed.js

@@ -0,0 +1,77 @@
+import { IntelError } from "../shared/intel-error/intel-error.js";
+// The separator inside the encoded cursor. `\0` cannot occur in either half: an ISO timestamp is
+// digits and punctuation, an Intel id is Crockford base32.
+const SEPARATOR = "\0";
+// ⚠️ The marker is what keeps an audit cursor out of this door and a feed cursor out of that one.
+// Both encode the same pair, and without it each would decode the other's position happily — then
+// read on from the wrong END of the journal. The damage would not look like an error: the feed
+// would simply start somewhere in the past and quietly leave out everything since.
+const MARKER = "f1";
+/**
+ * The pair, made into one string a reader cannot take apart by accident.
+ *
+ * ⚠️ This is not encryption and does not pretend to be. Anyone determined can decode base64url and
+ * read a timestamp. The point is the accident, not the attacker: a cursor that LOOKS like a
+ * timestamp invites a caller to send a timestamp, and a timestamp alone loses every second event
+ * written in the same millisecond.
+ */
+function encodeCursor(position) {
+    const raw = `${MARKER}${SEPARATOR}${position.occurredAt}${SEPARATOR}${position.id}`;
+    return btoa(String.fromCharCode(...new TextEncoder().encode(raw)))
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replaceAll("=", "");
+}
+function decodeCursor(cursor) {
+    // A cursor comes back from a consumer that stored it, possibly weeks ago, possibly truncated by
+    // whatever stored it, possibly meant for the other door. Every failure below is the same answer:
+    // this is not a cursor this door handed out. Guessing a position from a damaged one would move
+    // the reader in silence — past unread events, or back into ones already shown.
+    const refuse = () => new IntelError(400, "invalid_cursor", "The cursor is not one the feed issued. Pass back the nextCursor from a previous feed response unchanged, or omit it to start at the most recent event. A cursor from audit_list is not one of these.");
+    let raw;
+    try {
+        const padded = cursor.replaceAll("-", "+").replaceAll("_", "/");
+        const binary = atob(padded + "=".repeat((4 - (padded.length % 4)) % 4));
+        raw = new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0)));
+    }
+    catch {
+        throw refuse();
+    }
+    const parts = raw.split(SEPARATOR);
+    if (parts.length !== 3)
+        throw refuse();
+    const [marker, occurredAt, id] = parts;
+    if (marker !== MARKER)
+        throw refuse();
+    // ⚠️ Both halves are checked, not just the split. A cursor whose timestamp decoded to an empty
+    // string would compare as "before everything" and answer with an empty page forever.
+    if (occurredAt === undefined || occurredAt.length === 0)
+        throw refuse();
+    if (id === undefined || id.length === 0)
+        throw refuse();
+    return { occurredAt, id };
+}
+export function createFeed(deps) {
+    return {
+        async list(actor, input) {
+            const before = input.before === undefined ? null : decodeCursor(input.before);
+            // One more than asked for, so "is there another page" is answered by the same authorized
+            // query instead of a second one that could disagree with it.
+            const page = await deps.feed.listEvents(actor, {
+                before,
+                actor: input.actor ?? null,
+                limit: input.limit + 1,
+            });
+            const hasMore = page.events.length > input.limit;
+            const events = hasMore ? page.events.slice(0, input.limit) : page.events;
+            const last = events.at(-1);
+            return {
+                events,
+                // ⚠️ The cursor is the LAST DELIVERED row, never the probe row that was dropped. Taking it
+                // from the probe would skip exactly one event per page — the off-by-one that shows up as a
+                // change nobody saw, not as an error.
+                nextCursor: hasMore && last !== undefined ? encodeCursor(last) : null,
+            };
+        },
+    };
+}

package/dist/feed/feed.types.d.ts

@@ -0,0 +1,23 @@
+import type { FeedEvent, FeedListRequest, FeedListResponse } from "../contract/feed.js";
+import type { Actor } from "../nodes/nodes.types.js";
+export interface FeedPosition {
+    occurredAt: string;
+    id: string;
+}
+export interface FeedQuery {
+    before: FeedPosition | null;
+    actor: string | null;
+    limit: number;
+}
+export interface FeedPage {
+    events: FeedEvent[];
+}
+export interface FeedRepository {
+    listEvents(actor: Actor, query: FeedQuery): Promise<FeedPage>;
+}
+export interface FeedDeps {
+    feed: FeedRepository;
+}
+export interface FeedService {
+    list(actor: Actor, input: FeedListRequest): Promise<FeedListResponse>;
+}

package/dist/feed/feed.types.js

@@ -0,0 +1 @@
+export {};

package/dist/flows/flows.d.ts

@@ -0,0 +1,41 @@
+import type { FlowGraph, FlowNode } from "../contract/flow.js";
+import type { CompiledFlow, FlowDeps, FlowService } from "./flows.types.js";
+type SubflowNode = Extract<FlowNode, {
+    kind: "subflow";
+}>;
+type TreeLinkNode = Extract<FlowNode, {
+    kind: TreeLinkKind;
+}>;
+type ToolStepNode = Extract<FlowNode, {
+    kind: "tool";
+}>;
+export declare const treeLinkKinds: readonly ["folder", "document", "upload", "table"];
+type TreeLinkKind = (typeof treeLinkKinds)[number];
+/**
+ * One place reads a graph for each kind of step it contains, and everything else is derived from
+ * these three. The publish-time rule, the freeze, the sidebar, the relation graph, the requirements
+ * list and the repository's cycle walk all ask about the same nodes; a second `kind === "…"` walk
+ * beside them would drift quietly, because both would keep returning something plausible.
+ */
+export declare function subflowNodes(graph: FlowGraph): SubflowNode[];
+export declare function treeLinkNodes(graph: FlowGraph): TreeLinkNode[];
+export declare function toolNodes(graph: FlowGraph): ToolStepNode[];
+export declare function resourceIdOf(node: TreeLinkNode): string;
+export declare function calleeIds(graph: FlowGraph): string[];
+/**
+ * The documents a graph names and the tool SERVERS it reaches for, flattened and without repetition.
+ * The requirements list, the publish-time check and the run's first tool check read this one answer,
+ * so they cannot disagree about what a flow touches. A caller that needs to know *which step* names
+ * a document reads the node lists above instead — the relation graph draws exactly that edge.
+ *
+ * ⚠️ Servers, not functions, since #489. A step no longer names one function, so "what does this
+ * flow need" cannot be answered with a function list any more — and answering it with the functions
+ * a step MIGHT call would be a guess about a choice that is made while the flow runs.
+ */
+export declare function graphReferences(graph: FlowGraph): {
+    nodes: string[];
+    servers: string[];
+};
+export declare function compileFlow(graph: FlowGraph): CompiledFlow;
+export declare function createFlows(deps: FlowDeps): FlowService;
+export {};