lorenz 0.1.0

package/packages/mcp/dist/agentEndpoint.js

@@ -0,0 +1,270 @@
+import { httpUrlHost, isRecord, normalizeHttpBindHost, } from "@lorenz/domain";
+import { startMcpServer } from "./server.js";
+import { issueMcpToken, mcpAuthScopeForSettings, revokeMcpToken } from "./auth.js";
+export function trackerMcpServerName(kind) {
+    return `symphony_${(kind ?? "tracker").replace(/[^A-Za-z0-9_]/g, "_")}`;
+}
+const mcpPath = "/mcp";
+const configuredMcpProbeId = "symphony-configured-mcp-probe";
+const localMcpServers = new Map();
+const localMcpServerLocks = new Map();
+export async function acquireAgentMcpEndpoint(settings, workerHost, tunnels) {
+    let endpoint = null;
+    let token = null;
+    let released = false;
+    try {
+        const configuredToken = issueConfiguredMcpToken(settings);
+        token = configuredToken?.token ?? null;
+        endpoint = workerHost
+            ? await acquireRemoteMcpEndpoint(workerHost, settings, configuredToken, tunnels)
+            : await localMcpEndpoint(settings, configuredToken);
+        token ??= issueMcpToken(endpoint.authScope);
+        return {
+            url: endpoint.url,
+            token,
+            acpServer: () => ({
+                type: "http",
+                name: trackerMcpServerName(settings.tracker.kind),
+                url: endpoint?.url ?? "",
+                headers: [{ name: "Authorization", value: `Bearer ${token}` }],
+            }),
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                revokeMcpToken(token);
+                try {
+                    endpoint?.releaseTunnel?.();
+                }
+                finally {
+                    if (endpoint?.localServer)
+                        await releaseLocalMcpServer(endpoint.localServer);
+                }
+            },
+        };
+    }
+    catch (error) {
+        revokeMcpToken(token);
+        try {
+            endpoint?.releaseTunnel?.();
+        }
+        catch {
+            // The acquisition error below is the actionable failure; tunnel cleanup is best-effort.
+        }
+        if (endpoint?.localServer)
+            await releaseLocalMcpServer(endpoint.localServer);
+        throw error;
+    }
+}
+export async function acquireAgentMcpEndpointForRun(settings, workerHost, runKey, tunnels) {
+    let endpoint = null;
+    let token = null;
+    let released = false;
+    try {
+        const configuredToken = issueConfiguredMcpToken(settings);
+        token = configuredToken?.token ?? null;
+        endpoint = await acquirePerRunMcpEndpoint(workerHost, runKey, settings, configuredToken, tunnels);
+        token ??= issueMcpToken(endpoint.authScope);
+        return {
+            url: endpoint.url,
+            token,
+            acpServer: () => ({
+                type: "http",
+                name: trackerMcpServerName(settings.tracker.kind),
+                url: endpoint?.url ?? "",
+                headers: [{ name: "Authorization", value: `Bearer ${token}` }],
+            }),
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                revokeMcpToken(token);
+                tunnels.closeForRun(workerHost, runKey);
+                if (endpoint?.localServer)
+                    await releaseLocalMcpServer(endpoint.localServer);
+            },
+        };
+    }
+    catch (error) {
+        revokeMcpToken(token);
+        tunnels.closeForRun(workerHost, runKey);
+        if (endpoint?.localServer)
+            await releaseLocalMcpServer(endpoint.localServer);
+        throw error;
+    }
+}
+async function localMcpEndpoint(settings, configuredToken) {
+    const localServer = await ensureLocalMcpServer(settings, configuredToken);
+    const serverHost = normalizeHttpBindHost(settings.server.host);
+    const configuredPort = settings.server.port;
+    return {
+        url: localServer ? localServer.handle.url(mcpPath) : configuredLocalMcpUrl(settings),
+        authScope: configuredToken?.authScope ??
+            localServer?.handle.authScope ??
+            mcpAuthScopeForSettings(settings, serverHost, configuredPort),
+        localServer: localServer ?? undefined,
+    };
+}
+async function acquireRemoteMcpEndpoint(workerHost, settings, configuredToken, tunnels) {
+    if (!tunnels)
+        throw new Error("remote_acp_mcp_requires_tunnel_transport");
+    const localServer = await ensureLocalMcpServer(settings, configuredToken);
+    try {
+        const localHost = "127.0.0.1";
+        const localPort = localServer?.handle.port ?? settings.server.port;
+        if (typeof localPort !== "number" || localPort <= 0) {
+            throw new Error("remote_acp_mcp_requires_server_port");
+        }
+        const tunnel = await tunnels.acquireRemoteMcpTunnel(workerHost, localHost, localPort);
+        return {
+            url: `http://127.0.0.1:${tunnel.remotePort}${mcpPath}`,
+            authScope: configuredToken?.authScope ??
+                localServer?.handle.authScope ??
+                mcpAuthScopeForSettings(settings, normalizeHttpBindHost(settings.server.host), localPort),
+            releaseTunnel: () => tunnels.releaseRemoteMcpTunnel(tunnel),
+            localServer: localServer ?? undefined,
+        };
+    }
+    catch (error) {
+        if (localServer)
+            await releaseLocalMcpServer(localServer);
+        throw error;
+    }
+}
+async function acquirePerRunMcpEndpoint(workerHost, runKey, settings, configuredToken, tunnels) {
+    // The refcounted local MCP server is acquired BEFORE the per-run tunnel is
+    // opened. If anything after this point throws (notably `openForRun` failing
+    // to spawn the reverse tunnel), this function rejects before returning an
+    // McpEndpoint, so the caller never sees `localServer` and cannot release it.
+    // Drop the ref here so repeated tunnel-spawn failures don't leak refcounted
+    // local MCP servers / their listeners.
+    const localServer = await ensureLocalMcpServer(settings, configuredToken);
+    try {
+        const localHost = "127.0.0.1";
+        const localPort = localServer?.handle.port ?? settings.server.port;
+        if (typeof localPort !== "number" || localPort <= 0) {
+            throw new Error("remote_acp_mcp_requires_server_port");
+        }
+        const tunnel = await tunnels.openForRun(workerHost, runKey, localHost, localPort);
+        return {
+            url: `http://127.0.0.1:${tunnel.remotePort}${mcpPath}`,
+            authScope: configuredToken?.authScope ??
+                localServer?.handle.authScope ??
+                mcpAuthScopeForSettings(settings, normalizeHttpBindHost(settings.server.host), localPort),
+            localServer: localServer ?? undefined,
+        };
+    }
+    catch (error) {
+        if (localServer)
+            await releaseLocalMcpServer(localServer);
+        throw error;
+    }
+}
+async function ensureLocalMcpServer(settings, configuredToken) {
+    const configuredPort = settings.server.port;
+    const serverHost = normalizeHttpBindHost(settings.server.host);
+    if (typeof configuredPort === "number" && configuredPort > 0) {
+        const key = `${serverHost}:${configuredPort}`;
+        const identity = mcpAuthScopeForSettings(settings, serverHost, configuredPort);
+        if (!configuredToken || configuredToken.authScope !== identity) {
+            throw new Error("configured_mcp_token_scope_mismatch");
+        }
+        return withLocalMcpServerLock(key, async () => {
+            const existing = localMcpServers.get(key);
+            if (existing) {
+                if (existing.identity !== identity) {
+                    throw new Error("configured_mcp_server_conflict");
+                }
+                existing.refCount += 1;
+                return { key, handle: existing.handle };
+            }
+            if (await configuredMcpServerReachable(settings, configuredToken.token))
+                return null;
+            const handle = await startMcpServer(settings, {
+                host: serverHost,
+                port: configuredPort,
+                authScope: identity,
+            });
+            localMcpServers.set(key, { handle, identity, refCount: 1 });
+            return { key, handle };
+        });
+    }
+    const handle = await startMcpServer(settings, { host: serverHost, port: 0 });
+    return { key: null, handle };
+}
+function issueConfiguredMcpToken(settings) {
+    const configuredPort = settings.server.port;
+    if (typeof configuredPort !== "number" || configuredPort <= 0)
+        return null;
+    const serverHost = normalizeHttpBindHost(settings.server.host);
+    const authScope = mcpAuthScopeForSettings(settings, serverHost, configuredPort);
+    return { authScope, token: issueMcpToken(authScope) };
+}
+async function withLocalMcpServerLock(key, action) {
+    const previous = localMcpServerLocks.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    localMcpServerLocks.set(key, current);
+    await previous.catch(() => { });
+    try {
+        return await action();
+    }
+    finally {
+        release();
+        if (localMcpServerLocks.get(key) === current)
+            localMcpServerLocks.delete(key);
+    }
+}
+async function releaseLocalMcpServer(lease) {
+    if (lease.key === null) {
+        await lease.handle.stop();
+        return;
+    }
+    const key = lease.key;
+    await withLocalMcpServerLock(key, async () => {
+        const entry = localMcpServers.get(key);
+        if (!entry)
+            return;
+        if (entry.refCount > 1) {
+            entry.refCount -= 1;
+            return;
+        }
+        localMcpServers.delete(key);
+        await entry.handle.stop();
+    });
+}
+async function configuredMcpServerReachable(settings, token) {
+    const url = configuredLocalMcpUrl(settings);
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: configuredMcpProbeId,
+                method: "tools/list",
+            }),
+            signal: AbortSignal.timeout(250),
+        });
+        if (!response.ok)
+            return false;
+        const body = await response.json();
+        if (!isRecord(body) || body.jsonrpc !== "2.0" || body.id !== configuredMcpProbeId) {
+            return false;
+        }
+        const result = body.result;
+        return isRecord(result) && Array.isArray(result.tools);
+    }
+    catch {
+        return false;
+    }
+}
+function configuredLocalMcpUrl(settings) {
+    return `http://${httpUrlHost(settings.server.host)}:${settings.server.port}${mcpPath}`;
+}
+//# sourceMappingURL=agentEndpoint.js.map

package/packages/mcp/dist/agentEndpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentEndpoint.js","sourceRoot":"","sources":["../src/agentEndpoint.ts"],"names":[],"mappings":"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"}

package/packages/mcp/dist/auth.d.ts

@@ -0,0 +1,7 @@
+import type { Settings } from "@lorenz/domain";
+export declare function createMcpAuthScope(): string;
+export declare function mcpAuthScopeForSettings(settings: Settings, host: string, port: number | undefined): string;
+export declare function issueMcpToken(scope?: string): string;
+export declare function revokeMcpToken(token: string | null | undefined): void;
+export declare function validMcpToken(token: string | null | undefined, scope?: string): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/packages/mcp/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAK/C,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,MAAM,CAkBR;AAoBD,wBAAgB,aAAa,CAAC,KAAK,SAAsB,GAAG,MAAM,CAIjE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAErE;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,KAAK,SAAsB,GAC1B,OAAO,CAET"}

package/packages/mcp/dist/auth.js

@@ -0,0 +1,48 @@
+import { createHash, randomBytes } from "node:crypto";
+const defaultMcpAuthScope = "mcp:default";
+const activeTokens = new Map();
+export function createMcpAuthScope() {
+    return `mcp:${randomBytes(16).toString("base64url")}`;
+}
+export function mcpAuthScopeForSettings(settings, host, port) {
+    const tracker = settings.tracker;
+    const identity = JSON.stringify({
+        host,
+        port,
+        toolOptions: settings.toolOptions ? canonicalToolOptions(settings.toolOptions) : null,
+        tracker: {
+            kind: tracker.kind ?? null,
+            endpoint: tracker.endpoint ?? null,
+            apiKey: tracker.apiKey ?? null,
+            assignee: tracker.assignee ?? null,
+            options: canonicalRecord(tracker.options),
+            activeStates: tracker.activeStates,
+            terminalStates: tracker.terminalStates,
+            dispatch: tracker.dispatch,
+        },
+    });
+    return `mcp:${createHash("sha256").update(identity).digest("base64url")}`;
+}
+/** Key-sorted copy of a provider options record so equivalent configs hash identically. */
+function canonicalRecord(record) {
+    return Object.fromEntries(Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+/** Pack-name-sorted copy of the per-pack tool options with each pack's record canonical. */
+function canonicalToolOptions(toolOptions) {
+    return Object.fromEntries(Object.entries(toolOptions)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([pack, options]) => [pack, canonicalRecord(options)]));
+}
+export function issueMcpToken(scope = defaultMcpAuthScope) {
+    const token = randomBytes(32).toString("base64url");
+    activeTokens.set(token, scope);
+    return token;
+}
+export function revokeMcpToken(token) {
+    if (token)
+        activeTokens.delete(token);
+}
+export function validMcpToken(token, scope = defaultMcpAuthScope) {
+    return typeof token === "string" && activeTokens.get(token) === scope;
+}
+//# sourceMappingURL=auth.js.map

package/packages/mcp/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAItD,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAC1C,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE/C,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,QAAkB,EAClB,IAAY,EACZ,IAAwB;IAExB,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,IAAI;QACJ,IAAI;QACJ,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,oBAAoB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI;QACrF,OAAO,EAAE;YACP,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;YAClC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;YAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;YAClC,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC;YACzC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B;KACF,CAAC,CAAC;IACH,OAAO,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED,2FAA2F;AAC3F,SAAS,eAAe,CAAC,MAA+B;IACtD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACxE,CAAC;AACJ,CAAC;AAED,4FAA4F;AAC5F,SAAS,oBAAoB,CAC3B,WAAoD;IAEpD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC;SACxB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAC9D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAK,GAAG,mBAAmB;IACvD,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACpD,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAgC;IAC7D,IAAI,KAAK;QAAE,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,KAAgC,EAChC,KAAK,GAAG,mBAAmB;IAE3B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC;AACxE,CAAC"}

package/packages/mcp/dist/filter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A small query DSL backing the read tools of the structured trackers
+ * (`local_query` today). It is the composable, side-effect-free analog of `linear_graphql`'s
+ * read power: a query can never mutate the backend, so it carries no trust-boundary or
+ * atomicity risk and the agent can filter/project/sort/page freely.
+ *
+ * The DSL is intentionally total - no regex, no `eval`, no JSONPath - and is evaluated in
+ * memory over already-parsed records (a board `Issue[]`).
+ * Nesting depth and node count are bounded so a hostile or runaway filter cannot blow up.
+ */
+type Scalar = string | number | boolean | null;
+type Predicate = {
+    field: string;
+    op: "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
+    value: Scalar;
+} | {
+    field: string;
+    op: "in" | "nin";
+    value: Scalar[];
+} | {
+    field: string;
+    op: "contains";
+    value: string;
+    ci?: boolean;
+} | {
+    field: string;
+    op: "exists";
+    value: boolean;
+};
+export type Filter = Predicate | {
+    and: Filter[];
+} | {
+    or: Filter[];
+} | {
+    not: Filter;
+};
+interface OrderBy {
+    field: string;
+    dir: "asc" | "desc";
+}
+export interface QuerySpec {
+    where?: Filter;
+    orderBy: OrderBy[];
+    limit: number;
+    offset: number;
+}
+/**
+ * Validate untrusted agent input into a typed {@link Filter}, reconstructing each node so no
+ * stray properties survive. Throws a clear `Error` on malformed input or when the tree exceeds
+ * the depth/node bounds.
+ */
+export declare function parseFilter(input: unknown): Filter;
+/** Evaluate a validated {@link Filter} against a record. Side-effect free. */
+export declare function matchesFilter(record: Record<string, unknown>, filter: Filter): boolean;
+/**
+ * Parse the shared query envelope (`where`, `order_by`, `limit`, `offset`) from raw tool args.
+ * `select`, and any tracker-specific args, are parsed by the calling tool.
+ */
+export declare function parseQuerySpec(args: Record<string, unknown>): QuerySpec;
+/** Filter, then (stably) sort, then page a record list. Returns the page plus the pre-page total. */
+export declare function applyQuery<T extends Record<string, unknown>>(records: T[], spec: QuerySpec): {
+    rows: T[];
+    total: number;
+};
+/** Validate an optional `select` projection: an array of field-name strings, or undefined. */
+export declare function parseSelect(input: unknown): string[] | undefined;
+/** Project a record down to the named fields, dropping any the record does not have. */
+export declare function pickFields(record: Record<string, unknown>, fields: string[]): Record<string, unknown>;
+export {};
+//# sourceMappingURL=filter.d.ts.map

package/packages/mcp/dist/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,KAAK,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/C,KAAK,SAAS,GACV;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,GAAG,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GACpD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9D;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,MAAM,GAAG,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAExF,UAAU,OAAO;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,KAAK,GAAG,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAElD;AAoED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAKtF;AAuCD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAOvE;AAED,qGAAqG;AACrG,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,OAAO,EAAE,CAAC,EAAE,EACZ,IAAI,EAAE,SAAS,GACd;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAO9B;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAMhE;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,EAAE,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB"}

package/packages/mcp/dist/filter.js

@@ -0,0 +1,231 @@
+import { isRecord } from "@symphony/domain";
+const MAX_FILTER_DEPTH = 12;
+const MAX_FILTER_NODES = 200;
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+const COMPARE_OPS = new Set(["eq", "ne", "lt", "lte", "gt", "gte"]);
+const SET_OPS = new Set(["in", "nin"]);
+/**
+ * Validate untrusted agent input into a typed {@link Filter}, reconstructing each node so no
+ * stray properties survive. Throws a clear `Error` on malformed input or when the tree exceeds
+ * the depth/node bounds.
+ */
+export function parseFilter(input) {
+    return parseNode(input, 1, { nodes: 0 });
+}
+function parseNode(input, depth, state) {
+    if (depth > MAX_FILTER_DEPTH) {
+        throw new Error(`filter nesting exceeds ${MAX_FILTER_DEPTH} levels`);
+    }
+    if (++state.nodes > MAX_FILTER_NODES) {
+        throw new Error(`filter has more than ${MAX_FILTER_NODES} nodes`);
+    }
+    if (!isRecord(input))
+        throw new Error("filter: each node must be an object");
+    const hasAnd = "and" in input;
+    const hasOr = "or" in input;
+    const hasNot = "not" in input;
+    if (hasAnd || hasOr || hasNot) {
+        if (Object.keys(input).length !== 1) {
+            throw new Error("filter: a combinator node must have exactly one of 'and', 'or', or 'not'");
+        }
+        if (hasNot)
+            return { not: parseNode(input.not, depth + 1, state) };
+        const key = hasAnd ? "and" : "or";
+        const arr = input[key];
+        if (!Array.isArray(arr) || arr.length === 0) {
+            throw new Error(`filter: '${key}' must be a non-empty array of filters`);
+        }
+        const parsed = arr.map((node) => parseNode(node, depth + 1, state));
+        return hasAnd ? { and: parsed } : { or: parsed };
+    }
+    const field = input.field;
+    const op = input.op;
+    if (typeof field !== "string" || field === "") {
+        throw new Error("filter: predicate 'field' must be a non-empty string");
+    }
+    if (typeof op !== "string")
+        throw new Error("filter: predicate 'op' must be a string");
+    if (COMPARE_OPS.has(op)) {
+        if (!isScalar(input.value)) {
+            throw new Error(`filter: '${op}' value must be a string, number, boolean, or null`);
+        }
+        return { field, op: op, value: input.value };
+    }
+    if (SET_OPS.has(op)) {
+        const value = input.value;
+        if (!Array.isArray(value) || !value.every(isScalar)) {
+            throw new Error(`filter: '${op}' value must be an array of scalars`);
+        }
+        return { field, op: op, value: value };
+    }
+    if (op === "contains") {
+        if (typeof input.value !== "string") {
+            throw new Error("filter: 'contains' value must be a string");
+        }
+        if (input.ci !== undefined && typeof input.ci !== "boolean") {
+            throw new Error("filter: 'contains' ci must be a boolean");
+        }
+        return input.ci === undefined
+            ? { field, op: "contains", value: input.value }
+            : { field, op: "contains", value: input.value, ci: input.ci };
+    }
+    if (op === "exists") {
+        if (typeof input.value !== "boolean") {
+            throw new Error("filter: 'exists' value must be a boolean");
+        }
+        return { field, op: "exists", value: input.value };
+    }
+    throw new Error(`filter: unknown op '${op}'`);
+}
+/** Evaluate a validated {@link Filter} against a record. Side-effect free. */
+export function matchesFilter(record, filter) {
+    if ("and" in filter)
+        return filter.and.every((f) => matchesFilter(record, f));
+    if ("or" in filter)
+        return filter.or.some((f) => matchesFilter(record, f));
+    if ("not" in filter)
+        return !matchesFilter(record, filter.not);
+    return matchesPredicate(record, filter);
+}
+function matchesPredicate(record, p) {
+    // An unknown/undefined field is "absent": every comparison is false, mirroring linear_graphql's
+    // "ask for a field you do not have, get null" ergonomics. Only `exists:false` matches absence.
+    const present = Object.prototype.hasOwnProperty.call(record, p.field) && record[p.field] !== undefined;
+    if (!present)
+        return p.op === "exists" && p.value === false;
+    const raw = record[p.field];
+    switch (p.op) {
+        case "exists":
+            return p.value === true;
+        case "eq":
+            return scalarEq(raw, p.value);
+        case "ne":
+            return !scalarEq(raw, p.value);
+        case "lt":
+        case "lte":
+        case "gt":
+        case "gte": {
+            const c = compare(raw, p.value);
+            if (c === null)
+                return false;
+            if (p.op === "lt")
+                return c < 0;
+            if (p.op === "lte")
+                return c <= 0;
+            if (p.op === "gt")
+                return c > 0;
+            return c >= 0;
+        }
+        case "in":
+            return p.value.some((v) => scalarEq(raw, v));
+        case "nin":
+            return !p.value.some((v) => scalarEq(raw, v));
+        case "contains":
+            if (typeof raw === "string")
+                return strIncludes(raw, p.value, p.ci);
+            if (Array.isArray(raw))
+                return raw.some((el) => strIncludes(String(el), p.value, p.ci));
+            return false;
+    }
+}
+/**
+ * Parse the shared query envelope (`where`, `order_by`, `limit`, `offset`) from raw tool args.
+ * `select`, and any tracker-specific args, are parsed by the calling tool.
+ */
+export function parseQuerySpec(args) {
+    const spec = { orderBy: [], limit: DEFAULT_LIMIT, offset: 0 };
+    if (args.where !== undefined && args.where !== null)
+        spec.where = parseFilter(args.where);
+    if (args.order_by !== undefined)
+        spec.orderBy = parseOrderBy(args.order_by);
+    if (args.limit !== undefined)
+        spec.limit = parseLimit(args.limit);
+    if (args.offset !== undefined)
+        spec.offset = parseOffset(args.offset);
+    return spec;
+}
+/** Filter, then (stably) sort, then page a record list. Returns the page plus the pre-page total. */
+export function applyQuery(records, spec) {
+    let filtered = spec.where
+        ? records.filter((r) => matchesFilter(r, spec.where))
+        : records.slice();
+    if (spec.orderBy.length > 0)
+        filtered = sortRecords(filtered, spec.orderBy);
+    const total = filtered.length;
+    return { rows: filtered.slice(spec.offset, spec.offset + spec.limit), total };
+}
+/** Validate an optional `select` projection: an array of field-name strings, or undefined. */
+export function parseSelect(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    if (!Array.isArray(input) || !input.every((s) => typeof s === "string")) {
+        throw new Error("select must be an array of field-name strings");
+    }
+    return input;
+}
+/** Project a record down to the named fields, dropping any the record does not have. */
+export function pickFields(record, fields) {
+    const out = {};
+    for (const f of fields) {
+        if (Object.prototype.hasOwnProperty.call(record, f))
+            out[f] = record[f];
+    }
+    return out;
+}
+function parseOrderBy(input) {
+    if (!Array.isArray(input))
+        throw new Error("order_by must be an array");
+    return input.map((item) => {
+        if (!isRecord(item) || typeof item.field !== "string" || item.field === "") {
+            throw new Error("order_by items must be { field: string, dir?: 'asc' | 'desc' }");
+        }
+        if (item.dir !== undefined && item.dir !== "asc" && item.dir !== "desc") {
+            throw new Error("order_by dir must be 'asc' or 'desc'");
+        }
+        return { field: item.field, dir: item.dir === "desc" ? "desc" : "asc" };
+    });
+}
+function parseLimit(input) {
+    if (typeof input !== "number" || !Number.isInteger(input) || input < 1) {
+        throw new Error("limit must be a positive integer");
+    }
+    return Math.min(input, MAX_LIMIT);
+}
+function parseOffset(input) {
+    if (typeof input !== "number" || !Number.isInteger(input) || input < 0) {
+        throw new Error("offset must be a non-negative integer");
+    }
+    return input;
+}
+function sortRecords(records, orderBy) {
+    return [...records].sort((a, b) => {
+        for (const { field, dir } of orderBy) {
+            const c = compare(a[field], b[field]);
+            if (c !== null && c !== 0)
+                return dir === "desc" ? -c : c;
+        }
+        return 0;
+    });
+}
+function scalarEq(a, b) {
+    return a === b;
+}
+/** Compare two values when both are numbers or both are strings; otherwise incomparable (null). */
+function compare(a, b) {
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    if (typeof a === "string" && typeof b === "string")
+        return a < b ? -1 : a > b ? 1 : 0;
+    return null;
+}
+function strIncludes(haystack, needle, ci) {
+    return ci ? haystack.toLowerCase().includes(needle.toLowerCase()) : haystack.includes(needle);
+}
+function isScalar(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+//# sourceMappingURL=filter.js.map