@m6d/cortex-cli 0.1.0

package/src/contracts/client-tools/index.ts

@@ -0,0 +1,82 @@
+/**
+ * The embed ↔ widget handshake for client tools.
+ *
+ * A page embedded by the chat widget (a hosted checkout, signing page, …)
+ * reports its outcome with:
+ *
+ *     window.parent.postMessage(
+ *         { type: "cortex:client-tool", status: "completed", reference: "session_123" },
+ *         "*",
+ *     );
+ *
+ * The widget accepts the message only when the event's origin matches the
+ * tool's configured `embedOrigin`. The payload is the page's claim, relayed to
+ * the agent as-is: cortex does not verify it, and anything that must actually
+ * be true lives in the integrating backend's own records.
+ *
+ * Like the wire seam, this file is compiled into the client SDKs and must stay
+ * free of runtime dependencies. It is also the spec any future SDK (Flutter)
+ * reimplements against.
+ */
+
+export const CLIENT_TOOL_MESSAGE_TYPE = "cortex:client-tool";
+
+export const CLIENT_TOOL_STATUSES = ["completed", "cancelled", "failed"] as const;
+
+export type ClientToolStatus = (typeof CLIENT_TOOL_STATUSES)[number];
+
+/**
+ * What the browser answers a client tool call with, whoever produced it: an
+ * embedded page's handshake or one of the widget's own input components.
+ * The model reads this envelope as the tool result.
+ */
+export type ClientToolOutcome<TResult = unknown> = {
+    status: ClientToolStatus;
+    /** Opaque id for the integrating backend's own bookkeeping (session id, envelope id, …). */
+    reference?: string;
+    /** Optional payload passed through to the agent as part of the tool result. */
+    result?: TResult;
+};
+
+export type ClientToolHandshake = ClientToolOutcome & {
+    type: typeof CLIENT_TOOL_MESSAGE_TYPE;
+};
+
+/*
+ * Built-in input tools: static client tools the server package exports and
+ * the widget answers with a component of its own, keyed by tool name. A
+ * consumer's `toolComponents` entry under the same name replaces the built-in.
+ */
+
+export const REQUEST_LOCATION_TOOL = "requestLocation";
+
+export type LatLng = { lat: number; lng: number };
+
+/** The model's arguments: where the map opens; a world view when omitted. */
+export type RequestLocationInput = { center?: LatLng };
+
+/** The picked point, with the browser's accuracy radius in metres when it came from geolocation. */
+export type LocationResult = LatLng & { accuracy?: number };
+
+export type RequestLocationOutcome = ClientToolOutcome<LocationResult>;
+
+/**
+ * Parse a `message` event into a handshake, or null when the origin doesn't
+ * match the tool's `embedOrigin` or the payload isn't a well-formed handshake.
+ * Call from the widget's `message` listener with `event.data` / `event.origin`.
+ */
+export function parseClientToolHandshake(data: unknown, origin: string, embedOrigin: string) {
+    if (origin !== embedOrigin) return null;
+    if (typeof data !== "object" || data === null) return null;
+    const message = data as Record<string, unknown>;
+    if (message["type"] !== CLIENT_TOOL_MESSAGE_TYPE) return null;
+    const status = CLIENT_TOOL_STATUSES.find((known) => known === message["status"]);
+    if (!status) return null;
+    const reference = message["reference"];
+    return {
+        type: CLIENT_TOOL_MESSAGE_TYPE,
+        status,
+        ...(typeof reference === "string" ? { reference } : {}),
+        ...(message["result"] !== undefined ? { result: message["result"] } : {}),
+    } satisfies ClientToolHandshake;
+}

package/src/contracts/egress/index.ts

@@ -0,0 +1,161 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import type { LookupFunction } from "node:net";
+import { Agent } from "undici";
+
+/*
+ * The outbound network policy for URLs a tenant controls (tool endpoints,
+ * per-agent JWKS URIs): private, loopback, link-local, and metadata ranges are
+ * refused, and DNS is pinned so a rebind cannot slip a private address past
+ * the check, and credentials an answer echoes back are redacted from it.
+ * Shared by cc and the server, vendored like the rest of this package.
+ */
+
+export { credentialForms, scrubCredentialStrings } from "./scrub";
+
+type Range = { first: number; last: number };
+
+/** IPv4 /8 and /16 blocks that never denote a public host, as `[a, b]` octet ranges. */
+const BLOCKED_V4 = [
+    { a: 0 },
+    { a: 10 },
+    { a: 127 },
+    { a: 100, b: { first: 64, last: 127 } },
+    { a: 169, b: { first: 254, last: 254 } },
+    { a: 172, b: { first: 16, last: 31 } },
+    { a: 192, b: { first: 168, last: 168 } },
+    { a: 198, b: { first: 18, last: 19 } },
+] satisfies Array<{ a: number; b?: Range }>;
+
+/** Multicast and reserved: everything from 224.0.0.0 up. */
+const BLOCKED_V4_FROM = 224;
+
+function isBlockedV4(address: string) {
+    const [a = 0, b = 0] = address.split(".").map(Number);
+    if (a >= BLOCKED_V4_FROM) return true;
+    return BLOCKED_V4.some(
+        (block) => block.a === a && (!block.b || (b >= block.b.first && b <= block.b.last)),
+    );
+}
+
+function isBlockedV6(address: string) {
+    const normalized = address.toLowerCase();
+    if (normalized.startsWith("::ffff:")) {
+        const mapped = normalized.slice("::ffff:".length);
+        return isIP(mapped) === 4 ? isBlockedV4(mapped) : true;
+    }
+    return (
+        normalized === "::" ||
+        normalized === "::1" ||
+        normalized.startsWith("fc") ||
+        normalized.startsWith("fd") ||
+        /^fe[89ab]/.test(normalized)
+    );
+}
+
+/**
+ * Whether an IP address may be dialed. `EGRESS_ALLOW_PRIVATE_NETWORK=true` is
+ * the development opt-out for localhost and private demo backends; it disables
+ * every range check and must never be set in production.
+ */
+export function isBlockedAddress(address: string) {
+    if (process.env.EGRESS_ALLOW_PRIVATE_NETWORK === "true") return false;
+    return isIP(address) === 6 ? isBlockedV6(address) : isBlockedV4(address);
+}
+
+/**
+ * Whether a credential may travel to this URL: over TLS anywhere, or over
+ * plain http to loopback alone, for a service on the developer's machine.
+ */
+export function isTlsOrLoopback(url: string) {
+    try {
+        const { protocol, hostname } = new URL(url);
+        if (protocol === "https:") return true;
+        return (
+            protocol === "http:" &&
+            (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]")
+        );
+    } catch {
+        return false;
+    }
+}
+
+export function egressError() {
+    const error: NodeJS.ErrnoException = new Error("egress blocked");
+    error.code = "EGRESS_BLOCKED";
+    return error;
+}
+
+/** True when `error` or any of its causes is the egress refusal. */
+export function isEgressError(error: unknown) {
+    for (let current = error; current instanceof Error; current = current.cause) {
+        if ((current as NodeJS.ErrnoException).code === "EGRESS_BLOCKED") return true;
+    }
+    return false;
+}
+
+/**
+ * Re-resolves the hostname and re-validates every candidate on every connection
+ * attempt, handing the socket only vetted public addresses. The address dialed
+ * is the exact one just checked, so a nameserver cannot return a public IP to
+ * the check and a private one to the connect. Server name / Host header stay
+ * the original hostname.
+ */
+const pinnedLookup: LookupFunction = (hostname, options, callback) => {
+    lookup(hostname, { all: true, verbatim: true }).then(
+        (addresses) => {
+            const first = addresses[0];
+            if (!first || addresses.some((address) => isBlockedAddress(address.address))) {
+                callback(egressError(), "", 0);
+                return;
+            }
+            if (options.all) {
+                callback(
+                    null,
+                    addresses.map((address) => ({
+                        address: address.address,
+                        family: address.family,
+                    })),
+                );
+                return;
+            }
+            callback(null, first.address, first.family);
+        },
+        (error: unknown) =>
+            callback(error instanceof Error ? error : new Error("lookup failed"), "", 0),
+    );
+};
+
+/**
+ * Checks a URL before any socket opens: http(s) only, no embedded credentials,
+ * an optional exact-host allowlist, and every resolved address public. Returns
+ * the bare hostname on success. `pinnedLookup` re-checks at connect time; this
+ * is the cheap, clean refusal for a statically bad target.
+ */
+export async function checkEgressTarget(target: URL, allowedHostnames?: string[]) {
+    const hostname = target.hostname.replace(/^\[(.*)]$/, "$1");
+    const normalize = (host: string) => host.toLowerCase().replace(/\.$/, "");
+
+    if (!["http:", "https:"].includes(target.protocol) || target.username || target.password) {
+        return false;
+    }
+    if (allowedHostnames && !allowedHostnames.map(normalize).includes(normalize(hostname))) {
+        return false;
+    }
+
+    const preflight = await lookup(hostname, { all: true, verbatim: true });
+    return preflight.length > 0 && !preflight.some((address) => isBlockedAddress(address.address));
+}
+
+/**
+ * An undici dispatcher whose every connection resolves through `pinnedLookup`.
+ * Call the returned `release` once the response has been read; Bun's undici
+ * Agent may lack `close`, so release tolerates its absence.
+ */
+export function guardedDispatcher() {
+    const dispatcher = new Agent({ connect: { lookup: pinnedLookup } });
+    const release = () => {
+        if (typeof dispatcher.close === "function") void dispatcher.close().catch(() => undefined);
+    };
+    return { dispatcher, release };
+}

package/src/contracts/egress/scrub.ts

@@ -0,0 +1,59 @@
+const REDACTION_MARKER = "[REDACTED]";
+
+/**
+ * Every spelling of one credential an upstream may echo back. The value
+ * itself and, after a leading scheme word (`Bearer xyz`, `Basic abc`), the
+ * bare secret the scheme merely labels; each of those raw as in a header,
+ * percent-encoded as in a path slot (`encodeURIComponent`) or a query value
+ * (`URLSearchParams`, which spells a space as `+`), and JSON-escaped as inside
+ * a request body. The scrubber replaces longer forms first.
+ */
+export function credentialForms(value: string) {
+    const bare = /^[A-Za-z][\w.-]* +(\S.*)$/.exec(value)?.[1];
+    return [
+        ...new Set(
+            (bare ? [value, bare] : [value]).flatMap((form) => [
+                form,
+                encodeURIComponent(form),
+                new URLSearchParams({ v: form }).toString().slice(2),
+                JSON.stringify(form).slice(1, -1),
+            ]),
+        ),
+    ];
+}
+
+/**
+ * The one boundary every upstream body crosses before it is stored or sent
+ * on, in cc and the server alike: U+0000 is dropped from keys and values
+ * because Postgres refuses it in text and jsonb on both cc's execution log
+ * and the server's transcript, then the credentials the request presented
+ * are redacted. Dropping first, on the patterns as well, means a credential
+ * an upstream spelled with U+0000 inside it still matches; redacting first
+ * would let the strip reassemble it.
+ */
+export function scrubCredentialStrings(value: unknown, credentials: string[]): unknown {
+    const dropU0000 = (text: string) => text.replaceAll("\u0000", "");
+    // Longest first: a credential's encoded spelling often contains its raw
+    // form, and replacing the raw form first would leave a mangled, still
+    // recognizable remainder of the longer one.
+    const ordered = [...new Set(credentials.map(dropU0000).filter(Boolean))].sort(
+        (a, b) => b.length - a.length,
+    );
+    const scrub = (text: string) =>
+        ordered.reduce(
+            (safe, credential) => safe.replaceAll(credential, REDACTION_MARKER),
+            dropU0000(text),
+        );
+
+    if (typeof value === "string") return scrub(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => scrubCredentialStrings(item, credentials));
+    }
+    if (typeof value !== "object" || value === null) return value;
+    return Object.fromEntries(
+        Object.entries(value).map(([name, child]) => [
+            scrub(name),
+            scrubCredentialStrings(child, credentials),
+        ]),
+    );
+}

package/src/contracts/graph/clients/embed.ts

@@ -0,0 +1,45 @@
+/**
+ * Embeddings, which both halves of the graph need: `@m6d/cortex-cli` embeds every
+ * concept description as it seeds, `@m6d/cortex-server` embeds every prompt as it
+ * resolves. Two embedders would mean two vector spaces, so there is one. A bare
+ * `fetch` to the OpenAI-compatible `/embeddings` call keeps this package
+ * dependency-free. Everything under `graph/` compiles into an Angular library
+ * too, so it is written to the oldest target any consumer builds against.
+ */
+
+/** Everything cortex needs to reach one OpenAI-compatible embeddings endpoint. */
+export type EmbeddingProviderConfig = {
+    baseURL: string;
+    apiKey: string;
+    modelName: string;
+};
+
+/** Turns a batch of strings into their vectors, in the order given. */
+export type EmbedFn = (values: string[]) => Promise<number[][]>;
+
+export function createEmbedder(config: EmbeddingProviderConfig) {
+    const url = `${config.baseURL.replace(/\/+$/, "")}/embeddings`;
+
+    return async function embed(values: string[]) {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify({ model: config.modelName, input: values }),
+        });
+
+        if (!response.ok) {
+            throw new Error(
+                `Embedding request failed (${response.status}): ${await response.text()}`,
+            );
+        }
+
+        // The API is free to return entries out of order; `index` is authoritative.
+        const body = (await response.json()) as { data: { index: number; embedding: number[] }[] };
+        return [...body.data]
+            .sort((left, right) => left.index - right.index)
+            .map((entry) => entry.embedding);
+    };
+}

package/src/contracts/graph/clients/neo4j.ts

@@ -0,0 +1,85 @@
+/**
+ * Neo4j over its HTTP transaction endpoint, shared by the graph's writer (the
+ * CLI seeder) and its reader (the server resolver). Configuration is explicit
+ * and the transport is `fetch`, so this package stays dependency-free.
+ */
+
+import type { EmbedFn } from "./embed";
+
+export type Neo4jConfig = {
+    url: string;
+    user: string;
+    password: string;
+};
+
+export type Neo4jRow = Record<string, unknown>;
+
+export type Neo4jClient = {
+    /** Runs one statement and returns its rows as column-keyed objects. Throws `Neo4jQueryError` on any failure. */
+    query(cypher: string, parameters?: Record<string, unknown>): Promise<Neo4jRow[]>;
+};
+
+export class Neo4jQueryError extends Error {
+    public constructor(
+        message: string,
+        /** Neo4j's error code (`Neo.ClientError.…`), or the HTTP status when the request itself failed. */
+        public readonly code: string,
+    ) {
+        super(message);
+        this.name = "Neo4jQueryError";
+    }
+}
+
+/**
+ * Parameters whose key starts with `#` are embedded before the statement runs:
+ * `{ "#embedding": "text" }` becomes `{ embedding: number[] }`.
+ */
+export function createNeo4jClient(config: Neo4jConfig, embed?: EmbedFn) {
+    async function query(cypher: string, parameters: Record<string, unknown> = {}) {
+        const embeddedKeys = Object.keys(parameters).filter((key) => key.startsWith("#"));
+        if (embeddedKeys.length) {
+            if (!embed) throw new Error("An embedder is required when using # parameters");
+            const embeddings = await embed(embeddedKeys.map((key) => parameters[key] as string));
+            embeddedKeys.forEach((key, index) => {
+                delete parameters[key];
+                parameters[key.slice(1)] = embeddings[index]!;
+            });
+        }
+
+        const response = await fetch(`${config.url}/db/neo4j/tx/commit`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Basic ${btoa(`${config.user}:${config.password}`)}`,
+            },
+            body: JSON.stringify({ statements: [{ statement: cypher, parameters }] }),
+        });
+        if (!response.ok) {
+            throw new Neo4jQueryError(
+                `Neo4j request failed with status ${response.status}`,
+                String(response.status),
+            );
+        }
+
+        const result = (await response.json()) as {
+            errors?: { code?: string; message: string }[];
+            results: { columns: string[]; data: { row: unknown[] }[] }[];
+        };
+        if (result.errors?.length) {
+            throw new Neo4jQueryError(
+                result.errors.map((error) => error.message).join("; "),
+                result.errors[0]!.code ?? "unknown",
+            );
+        }
+
+        const queryResult = result.results[0];
+        if (!queryResult) return [];
+        return queryResult.data.map((entry) =>
+            Object.fromEntries(
+                queryResult.columns.map((column, index) => [column, entry.row[index]]),
+            ),
+        );
+    }
+
+    return { query } satisfies Neo4jClient;
+}

package/src/contracts/graph/helpers.ts

@@ -0,0 +1,57 @@
+/**
+ * Helper functions for building knowledge graph seed data. Projects author
+ * domains with these; `@m6d/cortex-server` re-exports them so authoring needs
+ * exactly one import path.
+ */
+
+import type {
+    ConceptDef,
+    DomainDef,
+    EndpointDef,
+    EndpointInput,
+    RuleDef,
+    ServiceDef,
+} from "./types";
+
+export function defineConcept(def: Omit<ConceptDef, "__brand">) {
+    return { __brand: "concept" as const, ...def };
+}
+
+export function defineRule(def: Omit<RuleDef, "__brand">) {
+    return { __brand: "rule" as const, ...def };
+}
+
+export function defineService(def: Omit<ServiceDef, "__brand">) {
+    return { __brand: "service" as const, ...def };
+}
+
+export function defineDomain(def: Omit<DomainDef, "__brand">) {
+    return { __brand: "domain" as const, ...def };
+}
+
+export function defineEndpoint(input: EndpointInput) {
+    const propertiesDescriptions = input.propertiesDescriptions ?? {};
+
+    const normalized = input.autoGenerated;
+
+    return {
+        __brand: "endpoint" as const,
+        name: input.name,
+        description: input.description ?? input.name,
+        path: input.path,
+        method: input.method,
+        propertiesDescriptions,
+        params: normalized ? [...normalized.params] : [],
+        body: normalized ? [...normalized.body] : [],
+        response: normalized ? [...normalized.response] : [],
+        successStatus: normalized?.successStatus ?? 200,
+        errorStatuses: normalized ? [...normalized.errorStatuses] : [],
+        responseKind: normalized?.responseKind ?? "object",
+        queries: input.queries,
+        mutates: input.mutates,
+        returns: input.returns,
+        dependsOn: input.dependsOn,
+        governedBy: input.governedBy,
+        metadata: input.metadata,
+    } satisfies EndpointDef;
+}

package/src/contracts/graph/index.ts

@@ -0,0 +1,30 @@
+/**
+ * The graph contract — the knowledge-graph vocabulary, authoring types and
+ * clients that `@m6d/cortex-cli` writes with and `@m6d/cortex-server` reads
+ * with. `@m6d/cortex-server` re-exports all of it, so a project authoring
+ * domains still has exactly one import path.
+ */
+
+export type { GraphSchema } from "./schema";
+export { GRAPH_SCHEMA, GRAPH_SCHEMA_VERSION } from "./schema";
+
+export type {
+    EndpointScalarType,
+    EndpointProperty,
+    ResponseKind,
+    AutoGenerated,
+    ConceptDef,
+    EndpointDef,
+    EndpointInput,
+    ServiceDef,
+    RuleDef,
+    DomainDef,
+} from "./types";
+
+export { defineConcept, defineRule, defineService, defineDomain, defineEndpoint } from "./helpers";
+
+export type { Neo4jConfig, Neo4jClient, Neo4jRow } from "./clients/neo4j";
+export { createNeo4jClient, Neo4jQueryError } from "./clients/neo4j";
+
+export type { EmbedFn, EmbeddingProviderConfig } from "./clients/embed";
+export { createEmbedder } from "./clients/embed";

package/src/contracts/graph/schema.ts

@@ -0,0 +1,65 @@
+/**
+ * The contract between the graph's writer and its reader.
+ *
+ * Seeding lives in `@m6d/cortex-cli` and resolution lives in `@m6d/cortex-server`,
+ * two packages a project installs and upgrades separately. The labels, relationship
+ * types, property names and index name they agree on are this module, here, so
+ * neither side owns the vocabulary the other has to match.
+ *
+ * A mismatch between the two is invisible at runtime: the resolver's Cypher
+ * matches nothing and retrieval comes back empty rather than failing. That is what
+ * `GRAPH_SCHEMA_VERSION` is for — bump it on any change to the shape below. The
+ * CLI stamps the version it wrote onto the graph and the server checks that stamp
+ * on its first resolve, so skew surfaces as an error instead of as silence.
+ */
+
+export const GRAPH_SCHEMA_VERSION = 1;
+
+export const GRAPH_SCHEMA = {
+    label: {
+        domain: "Domain",
+        concept: "Concept",
+        endpoint: "Endpoint",
+        service: "Service",
+        rule: "Rule",
+        /** Stamped with the version above, so a stale graph is detectable later. */
+        marker: "CortexGraph",
+    },
+    rel: {
+        belongsTo: "BELONGS_TO",
+        specializes: "SPECIALIZES",
+        queriedVia: "QUERIED_VIA",
+        mutatedVia: "MUTATED_VIA",
+        returns: "RETURNS",
+        dependsOn: "DEPENDS_ON",
+        governs: "GOVERNS",
+        requestedVia: "REQUESTED_VIA",
+    },
+    prop: {
+        name: "name",
+        description: "description",
+        aliases: "aliases",
+        metadata: "metadata",
+        path: "path",
+        method: "method",
+        params: "params",
+        body: "body",
+        response: "response",
+        propertiesDescriptions: "propertiesDescriptions",
+        successStatus: "successStatus",
+        errorStatuses: "errorStatuses",
+        builtInId: "builtInId",
+        embedding: "embedding",
+        /** On a RETURNS edge: which part of the response carries the concept. */
+        field: "field",
+        /** On a DEPENDS_ON edge. */
+        paramName: "paramName",
+        fromField: "fromField",
+        /** On the marker node. */
+        version: "version",
+    },
+    /** Created by the CLI's seeder, queried by name in the resolver's first hop. */
+    conceptEmbeddingsIndex: "concept_embeddings",
+} as const;
+
+export type GraphSchema = typeof GRAPH_SCHEMA;