agent-trellis 0.6.3 → 0.8.0

package/dist/lib/mcpRuntime.js

@@ -0,0 +1,185 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { allocateExposedToolNames } from "./mcpToolRegistry.js";
+function compactBuiltinToolName(name) {
+    return name.startsWith("trellis.") ? name.slice("trellis.".length).replaceAll(".", "_") : name;
+}
+function providerError(provider, error) {
+    return `trellis-mcp-runtime: provider "${provider}" failed: ${error instanceof Error ? error.message : String(error)}`;
+}
+export class BuiltinRegistry {
+    providers;
+    warn;
+    toolOwners = new Map();
+    originalToolOwners = new Map();
+    exposedToOriginal = new Map();
+    resourceOwners = new Map();
+    promptOwners = new Map();
+    constructor(providers, warn = console.error) {
+        this.providers = providers;
+        this.warn = warn;
+    }
+    async listTools(context) {
+        const candidates = [];
+        this.toolOwners.clear();
+        this.originalToolOwners.clear();
+        this.exposedToOriginal.clear();
+        for (const provider of this.providers) {
+            if (!provider.listTools)
+                continue;
+            try {
+                for (const tool of await provider.listTools(context)) {
+                    candidates.push({ provider, tool });
+                }
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        const exposedNames = allocateExposedToolNames(candidates.map(({ provider, tool }) => ({
+            serverName: provider.id,
+            toolName: provider.id === "upstream" ? tool.name : compactBuiltinToolName(tool.name),
+        })));
+        return candidates.map(({ provider, tool }, index) => {
+            const exposedName = exposedNames[index];
+            this.toolOwners.set(exposedName, provider);
+            this.exposedToOriginal.set(exposedName, tool.name);
+            if (!this.originalToolOwners.has(tool.name))
+                this.originalToolOwners.set(tool.name, provider);
+            const title = exposedName === tool.name || tool.title !== undefined
+                ? tool.title
+                : `${provider.id} / ${tool.name}`;
+            return { ...tool, name: exposedName, ...(title === undefined ? {} : { title }) };
+        });
+    }
+    async callTool(name, args, context) {
+        let provider = this.toolOwners.get(name);
+        let originalName = this.exposedToOriginal.get(name) ?? name;
+        if (!provider) {
+            await this.listTools(context);
+            provider = this.toolOwners.get(name);
+            originalName = this.exposedToOriginal.get(name) ?? name;
+            // Keep direct programmatic calls using the logical pre-normalization
+            // name working, while never advertising an invalid alias to an Agent.
+            if (!provider)
+                provider = this.originalToolOwners.get(name);
+        }
+        if (!provider)
+            return { content: [{ type: "text", text: `unknown Trellis tool "${name}"` }], isError: true };
+        try {
+            return await provider.callTool(originalName, args, context);
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: providerError(provider.id, err) }], isError: true };
+        }
+    }
+    async listResources(context) {
+        const resources = [];
+        this.resourceOwners.clear();
+        for (const provider of this.providers) {
+            if (!provider.listResources)
+                continue;
+            try {
+                for (const resource of await provider.listResources(context)) {
+                    if (this.resourceOwners.has(resource.uri)) {
+                        this.warn(`trellis-mcp-runtime: duplicate resource "${resource.uri}" from provider "${provider.id}"`);
+                        continue;
+                    }
+                    this.resourceOwners.set(resource.uri, provider);
+                    resources.push(resource);
+                }
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        return resources;
+    }
+    async readResource(uri, context) {
+        const key = uri.toString();
+        let provider = this.resourceOwners.get(key);
+        if (!provider) {
+            await this.listResources(context);
+            provider = this.resourceOwners.get(key);
+        }
+        if (!provider?.readResource)
+            throw new Error(`unknown Trellis resource "${key}"`);
+        return provider.readResource(uri, context);
+    }
+    async listPrompts(context) {
+        const prompts = [];
+        this.promptOwners.clear();
+        for (const provider of this.providers) {
+            if (!provider.listPrompts)
+                continue;
+            try {
+                for (const prompt of await provider.listPrompts(context)) {
+                    if (this.promptOwners.has(prompt.name)) {
+                        this.warn(`trellis-mcp-runtime: duplicate prompt "${prompt.name}" from provider "${provider.id}"`);
+                        continue;
+                    }
+                    this.promptOwners.set(prompt.name, provider);
+                    prompts.push(prompt);
+                }
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        return prompts;
+    }
+    async getPrompt(name, args, context) {
+        let provider = this.promptOwners.get(name);
+        if (!provider) {
+            await this.listPrompts(context);
+            provider = this.promptOwners.get(name);
+        }
+        if (!provider?.getPrompt)
+            throw new Error(`unknown Trellis prompt "${name}"`);
+        return provider.getPrompt(name, args, context);
+    }
+    async close() {
+        await Promise.all(this.providers.map(async (provider) => {
+            try {
+                await provider.close?.();
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }));
+    }
+}
+/** Adapts the existing gateway tool backend without duplicating its routing
+ * or upstream connection logic. */
+export class UpstreamProvider {
+    backend;
+    id = "upstream";
+    constructor(backend) {
+        this.backend = backend;
+    }
+    async listTools() {
+        return (await this.backend.listTools());
+    }
+    async callTool(name, args) {
+        return (await this.backend.callTool(name, args));
+    }
+    async close() {
+        await this.backend.close();
+    }
+}
+export function createRuntimeServer(serverInfo, context, registry) {
+    const server = new Server(serverInfo, {
+        capabilities: {
+            tools: { listChanged: true },
+            resources: { listChanged: true },
+            prompts: { listChanged: true },
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await registry.listTools(context) }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => registry.callTool(request.params.name, request.params.arguments, context));
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: await registry.listResources(context) }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => registry.readResource(new URL(request.params.uri), context));
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: await registry.listPrompts(context) }));
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => registry.getPrompt(request.params.name, request.params.arguments, context));
+    return server;
+}

package/dist/lib/mcpStatusProvider.d.ts

@@ -0,0 +1,10 @@
+import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { GatewayBackend } from "./gatewayBackend.js";
+import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+export declare class McpStatusProvider implements TrellisProvider {
+    private readonly backend;
+    readonly id = "mcp";
+    constructor(backend: GatewayBackend);
+    listTools(): Tool[];
+    callTool(name: string, _args: unknown, _context: RuntimeContext): Promise<CallToolResult>;
+}

package/dist/lib/mcpStatusProvider.js

@@ -0,0 +1,25 @@
+const STATUS_TOOL = {
+    name: "trellis.mcp.status",
+    description: "Show MCP upstream availability and the safe next action for authentication or configuration failures.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+export class McpStatusProvider {
+    backend;
+    id = "mcp";
+    constructor(backend) {
+        this.backend = backend;
+    }
+    listTools() {
+        return [STATUS_TOOL];
+    }
+    async callTool(name, _args, _context) {
+        if (name !== STATUS_TOOL.name)
+            return { content: [{ type: "text", text: `unknown MCP status tool "${name}"` }], isError: true };
+        const statuses = this.backend.listStatus?.() ?? [];
+        return {
+            content: [{ type: "text", text: JSON.stringify({ servers: statuses }, null, 2) }],
+            structuredContent: { servers: statuses },
+        };
+    }
+}

package/dist/lib/mcpToolRegistry.d.ts

@@ -33,6 +33,11 @@ export interface UpstreamTool {
     [key: string]: unknown;
 }
 export type AggregatedTool = UpstreamTool;
+/** The strictest Agent-facing tool-name contract currently exercised by the
+ * local stack (notably the Codex-compatible model tool surface). */
+export declare const MAX_EXPOSED_TOOL_NAME_LENGTH = 64;
+export declare const SHORT_EXPOSED_TOOL_NAME_LENGTH = 12;
+export declare const EXPOSED_TOOL_NAME_PATTERN: RegExp;
 /**
  * `${serverName}__${toolName}`, the separator every consumer of this
  * registry shares. Two underscores rather than one because single
@@ -41,7 +46,17 @@ export type AggregatedTool = UpstreamTool;
  * gateway matching it keeps one naming convention across both consumers.
  */
 export declare const TOOL_NAME_SEPARATOR = "__";
+/** Normalize one raw tool name without adding a server prefix. */
+export declare function normalizedToolName(toolName: string): string;
 export declare function prefixedToolName(serverName: string, toolName: string): string;
+export interface ToolNameCandidate {
+    serverName: string;
+    toolName: string;
+}
+/** Allocate all exposed names together so normalization collisions are
+ * deterministic and no upstream tool is silently lost. The returned array
+ * is indexed like `candidates`. */
+export declare function allocateExposedToolNames(candidates: readonly ToolNameCandidate[]): string[];
 export interface AddResult {
     /** Prefixed names actually registered by this call. */
     added: string[];
@@ -58,6 +73,8 @@ export interface AddResult {
 export declare class McpToolRegistry {
     private readonly entries;
     private readonly order;
+    private readonly candidates;
+    private rebuild;
     /**
      * Register one connected upstream's tools. Callers add each upstream
      * independently, so an upstream that failed to connect or to list its
@@ -65,6 +82,7 @@ export declare class McpToolRegistry {
      * aggregated, with no special-casing here.
      */
     add(serverName: string, upstream: ToolUpstream, tools: readonly AggregatedTool[]): AddResult;
+    private exposedNameFor;
     /** Every registered tool, under its prefixed name, in registration
      * order. Each tool's own `description`/`inputSchema` and any additional
      * fields the upstream sent are preserved verbatim; only `name` changes. */

package/dist/lib/mcpToolRegistry.js

@@ -13,6 +13,11 @@
  * forwarding client to a shared gateway service, both fit without this
  * module changing (design.md D11).
  */
+/** The strictest Agent-facing tool-name contract currently exercised by the
+ * local stack (notably the Codex-compatible model tool surface). */
+export const MAX_EXPOSED_TOOL_NAME_LENGTH = 64;
+export const SHORT_EXPOSED_TOOL_NAME_LENGTH = 12;
+export const EXPOSED_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
 /**
  * `${serverName}__${toolName}`, the separator every consumer of this
  * registry shares. Two underscores rather than one because single
@@ -21,12 +26,94 @@
  * gateway matching it keeps one naming convention across both consumers.
  */
 export const TOOL_NAME_SEPARATOR = "__";
+function stableHash(value) {
+    // FNV-1a is deliberately small and deterministic; this is only a bounded
+    // display-name disambiguator, never a security or persistence primitive.
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function safeSegment(value, fallback) {
+    const normalized = value.replace(/[^a-zA-Z0-9_-]+/g, "_");
+    return normalized || fallback;
+}
+function compactSourceSegment(value) {
+    const normalized = safeSegment(value, "server");
+    return safeSegment(normalized.replace(/^mcp(?:_|-)+/i, ""), "server");
+}
+function boundedName(value, identity) {
+    if (value.length <= MAX_EXPOSED_TOOL_NAME_LENGTH && EXPOSED_TOOL_NAME_PATTERN.test(value))
+        return value;
+    const suffix = `__${stableHash(identity)}`;
+    const prefixLength = Math.max(1, MAX_EXPOSED_TOOL_NAME_LENGTH - suffix.length);
+    return `${value.slice(0, prefixLength)}${suffix}`;
+}
+/** Normalize one raw tool name without adding a server prefix. */
+export function normalizedToolName(toolName) {
+    return boundedName(safeSegment(toolName, "tool"), `tool\0${toolName}`);
+}
 export function prefixedToolName(serverName, toolName) {
-    return `${serverName}${TOOL_NAME_SEPARATOR}${toolName}`;
+    const server = compactSourceSegment(serverName);
+    const tool = safeSegment(toolName, "tool");
+    return boundedName(`${server}${TOOL_NAME_SEPARATOR}${tool}`, `prefixed\0${serverName}\0${toolName}`);
+}
+/** Allocate all exposed names together so normalization collisions are
+ * deterministic and no upstream tool is silently lost. The returned array
+ * is indexed like `candidates`. */
+export function allocateExposedToolNames(candidates) {
+    const counts = new Map();
+    for (const candidate of candidates)
+        counts.set(candidate.toolName, (counts.get(candidate.toolName) ?? 0) + 1);
+    const ordered = candidates
+        .map((candidate, index) => ({ candidate, index }))
+        .sort((left, right) => left.candidate.serverName.localeCompare(right.candidate.serverName)
+        || left.candidate.toolName.localeCompare(right.candidate.toolName)
+        || left.index - right.index);
+    const allocated = new Array(candidates.length);
+    const used = new Set();
+    for (const { candidate, index } of ordered) {
+        const normalized = normalizedToolName(candidate.toolName);
+        const source = compactSourceSegment(candidate.serverName);
+        // A `__` segment is already a source-qualified name from an upstream
+        // registry (for example `fixture__env` reaching the Runtime provider).
+        // Do not add a second provider prefix around it.
+        const sourceQualified = normalized.includes("__") || normalized === source || normalized.startsWith(`${source}_`) || normalized.startsWith(`${source}__`);
+        const unique = (counts.get(candidate.toolName) ?? 0) === 1;
+        const base = unique && normalized.length > SHORT_EXPOSED_TOOL_NAME_LENGTH
+            ? normalized
+            : unique && sourceQualified
+                ? normalized
+                : prefixedToolName(candidate.serverName, candidate.toolName);
+        let exposed = base;
+        let suffix = 2;
+        while (used.has(exposed)) {
+            exposed = boundedName(`${base}${TOOL_NAME_SEPARATOR}${suffix}`, `collision\0${candidate.serverName}\0${candidate.toolName}\0${suffix}`);
+            suffix += 1;
+        }
+        used.add(exposed);
+        allocated[index] = exposed;
+    }
+    return allocated;
 }
 export class McpToolRegistry {
     entries = new Map();
     order = [];
+    candidates = [];
+    rebuild() {
+        this.entries.clear();
+        this.order.length = 0;
+        const allocated = allocateExposedToolNames(this.candidates);
+        const ordered = this.candidates
+            .map((candidate, index) => ({ candidate, index, exposed: allocated[index] }))
+            .sort((left, right) => left.candidate.serverName.localeCompare(right.candidate.serverName) || left.candidate.toolName.localeCompare(right.candidate.toolName) || left.index - right.index);
+        for (const { candidate, exposed } of ordered) {
+            this.entries.set(exposed, candidate);
+            this.order.push(exposed);
+        }
+    }
     /**
      * Register one connected upstream's tools. Callers add each upstream
      * independently, so an upstream that failed to connect or to list its
@@ -34,32 +121,36 @@ export class McpToolRegistry {
      * aggregated, with no special-casing here.
      */
     add(serverName, upstream, tools) {
-        const added = [];
-        const skipped = [];
-        for (const tool of tools) {
-            const name = prefixedToolName(serverName, tool.name);
-            if (this.entries.has(name)) {
-                skipped.push(name);
-                continue;
-            }
-            this.entries.set(name, { serverName, toolName: tool.name, upstream, tool });
-            this.order.push(name);
-            added.push(name);
+        for (const tool of tools)
+            this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+        this.rebuild();
+        const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== undefined);
+        return { added, skipped: [] };
+    }
+    exposedNameFor(serverName, toolName) {
+        for (const [name, entry] of this.entries) {
+            if (entry.serverName === serverName && entry.toolName === toolName)
+                return name;
         }
-        return { added, skipped };
+        return undefined;
     }
     /** Every registered tool, under its prefixed name, in registration
      * order. Each tool's own `description`/`inputSchema` and any additional
      * fields the upstream sent are preserved verbatim; only `name` changes. */
     listTools() {
+        this.rebuild();
         return this.order.map((name) => {
             const entry = this.entries.get(name);
-            return { ...entry.tool, name };
+            const title = name === entry.toolName || entry.tool.title !== undefined
+                ? entry.tool.title
+                : `${entry.serverName} / ${entry.toolName}`;
+            return { ...entry.tool, name, ...(title === undefined ? {} : { title }) };
         });
     }
     /** The owning upstream and original tool name for a prefixed name, or
      * `undefined` if nothing owns it. */
     resolve(prefixedName) {
+        this.rebuild();
         const entry = this.entries.get(prefixedName);
         if (!entry)
             return undefined;
@@ -80,6 +171,7 @@ export class McpToolRegistry {
     /** Distinct server names with at least one registered tool, in
      * registration order. */
     servers() {
+        this.rebuild();
         const seen = [];
         for (const name of this.order) {
             const { serverName } = this.entries.get(name);
@@ -89,6 +181,7 @@ export class McpToolRegistry {
         return seen;
     }
     get size() {
+        this.rebuild();
         return this.entries.size;
     }
 }

package/dist/lib/memoryGraph.d.ts

@@ -57,7 +57,7 @@ export interface MemorySyncPlan {
  * entity and every relation passes through completely untouched,
  * regardless of what canonical wants.
  */
-export declare function planMemorySync(canonical: Pick<CanonicalSource, "memories">, currentGraphContent: string | undefined): MemorySyncPlan;
+export declare function planMemorySync(canonical: Pick<CanonicalSource, "memories">, currentGraphContent: string | undefined, selectedMemoryNames?: readonly string[]): MemorySyncPlan;
 /**
  * Renders one extraction candidate as readable markdown — the entity's
  * real (unslugged) name as a heading, its type, its observations as a

package/dist/lib/memoryGraph.js

@@ -56,16 +56,20 @@ export function renderMemoryGraph(lines) {
  * entity and every relation passes through completely untouched,
  * regardless of what canonical wants.
  */
-export function planMemorySync(canonical, currentGraphContent) {
+export function planMemorySync(canonical, currentGraphContent, selectedMemoryNames) {
     const existingLines = currentGraphContent !== undefined ? parseMemoryGraph(currentGraphContent) : [];
     const untouchedLines = existingLines.filter((line) => !(line.type === "entity" && line.entityType === TRELLIS_MEMORY_ENTITY_TYPE));
     const existingTrellisEntities = new Map(existingLines.filter((line) => line.type === "entity" && line.entityType === TRELLIS_MEMORY_ENTITY_TYPE).map((e) => [e.name, e]));
     const existingOtherEntityNames = new Set(existingLines.filter((line) => line.type === "entity" && line.entityType !== TRELLIS_MEMORY_ENTITY_TYPE).map((e) => e.name));
+    const selected = selectedMemoryNames !== undefined ? new Set(selectedMemoryNames) : undefined;
+    const selectedMemories = selected ? canonical.memories.filter((memory) => selected.has(memory.name)) : canonical.memories;
     const items = [];
-    const nextTrellisEntities = [];
+    const nextTrellisEntities = selected
+        ? [...existingTrellisEntities.values()].filter((entity) => !selected.has(entity.name))
+        : [];
     let changed = false;
     const canonicalNames = new Set(canonical.memories.map((m) => m.name));
-    for (const memory of canonical.memories) {
+    for (const memory of selectedMemories) {
         if (existingOtherEntityNames.has(memory.name)) {
             items.push({ name: memory.name, action: "conflict", detail: `an entity named "${memory.name}" already exists in the graph and wasn't created by Trellis — resolve by hand` });
             continue;
@@ -90,6 +94,8 @@ export function planMemorySync(canonical, currentGraphContent) {
         }
     }
     for (const [name] of existingTrellisEntities) {
+        if (selected)
+            continue;
         if (canonicalNames.has(name))
             continue; // still wanted, handled above
         items.push({ name, action: "remove", detail: "no longer in canonical — will be removed from the graph" });

package/dist/lib/memoryProvider.d.ts

@@ -0,0 +1,58 @@
+import type { CallToolResult, ReadResourceResult, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Scope } from "../core/types.js";
+import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+/**
+ * The storage-independent boundary for memory providers. A future local
+ * graph or OpenViking adapter can implement this contract without changing
+ * the MCP edge or the agent-facing tool names.
+ *
+ * Providers are deliberately read-only here. Mutation needs a separate
+ * reviewed capability with explicit audit and approval semantics.
+ */
+export interface MemoryProvider {
+    readonly id: string;
+    list(context: RuntimeContext): readonly MemoryRef[] | Promise<readonly MemoryRef[]>;
+    read(name: string, context: RuntimeContext): MemorySourceDocument | undefined | Promise<MemorySourceDocument | undefined>;
+}
+export interface MemoryRef {
+    name: string;
+    scope?: Scope;
+}
+export interface MemorySourceDocument {
+    content: string;
+}
+export interface MemoryDocument {
+    name: string;
+    content: string;
+    fingerprint: string;
+    uri: string;
+    scope: "in-scope";
+    source: string;
+}
+export interface MemorySearchHit {
+    name: string;
+    fingerprint: string;
+    uri: string;
+    scope: "in-scope";
+    source: string;
+}
+/** The default provider reads only canonical Markdown memory files. */
+export declare class CanonicalMemoryProvider implements MemoryProvider {
+    readonly id = "canonical";
+    list(context: RuntimeContext): readonly MemoryRef[];
+    read(name: string, context: RuntimeContext): MemorySourceDocument | undefined;
+}
+/** Adapts any read-only MemoryProvider to Trellis's MCP provider registry. */
+export declare class RuntimeMemoryProvider implements TrellisProvider {
+    private readonly source;
+    readonly id = "memory";
+    constructor(source?: MemoryProvider);
+    listTools(): Tool[];
+    callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+    listResources(context: RuntimeContext): Promise<Resource[]>;
+    readResource(uri: URL, context: RuntimeContext): Promise<ReadResourceResult>;
+    private inScopeRefs;
+    private readDocument;
+    private search;
+    private readTool;
+}