agent-trellis 0.7.0 → 0.8.2

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;
+}

package/dist/lib/memoryProvider.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { isInScope } from "../core/adapter.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+const MAX_MEMORY_BYTES = 256 * 1024;
+const MEMORY_RESOURCE_PREFIX = "trellis://memories/";
+const SEARCH_TOOL = {
+    name: "trellis.memory.search",
+    description: "Search in-scope Trellis memories by name or content, then read one selected memory on demand.",
+    inputSchema: {
+        type: "object",
+        properties: { query: { type: "string" }, limit: { type: "number", minimum: 1, maximum: 50 } },
+        required: ["query"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+const READ_TOOL = {
+    name: "trellis.memory.read",
+    description: "Read one in-scope canonical Trellis memory as Markdown.",
+    inputSchema: {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+/** The default provider reads only canonical Markdown memory files. */
+export class CanonicalMemoryProvider {
+    id = "canonical";
+    list(context) {
+        return loadCanonicalSource(context.homeDir).memories.map(({ name, scope }) => ({ name, scope }));
+    }
+    read(name, context) {
+        const canonical = loadCanonicalSource(context.homeDir);
+        const memory = canonical.memories.find((candidate) => candidate.name === name);
+        if (!memory)
+            return undefined;
+        const memoryRoot = resolve(context.homeDir, ".trellis", "memories");
+        const root = realpathSync(memoryRoot);
+        const file = realpathSync(memory.file);
+        const relativePath = relative(root, file);
+        if (relativePath.startsWith(`..${sep}`) || relativePath === "..") {
+            throw new Error("memory file is outside the canonical memories directory");
+        }
+        const stat = statSync(file);
+        if (!stat.isFile())
+            throw new Error("memory path is not a file");
+        if (stat.size > MAX_MEMORY_BYTES)
+            throw new Error(`memory exceeds the ${MAX_MEMORY_BYTES}-byte provider limit`);
+        return { content: readFileSync(file, "utf8") };
+    }
+}
+function textResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: value };
+}
+function errorResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function fingerprint(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function memoryUri(name) {
+    return `${MEMORY_RESOURCE_PREFIX}${encodeURIComponent(name)}.md`;
+}
+function memoryNameFromUri(uri) {
+    if (uri.protocol !== "trellis:" || uri.hostname !== "memories") {
+        throw new Error(`unsupported memory resource URI "${uri.toString()}"`);
+    }
+    const segments = uri.pathname.split("/").filter(Boolean).map((segment) => decodeURIComponent(segment));
+    if (segments.length !== 1 || !segments[0].endsWith(".md")) {
+        throw new Error(`unsupported memory resource URI "${uri.toString()}"`);
+    }
+    return segments[0].slice(0, -3);
+}
+/** Adapts any read-only MemoryProvider to Trellis's MCP provider registry. */
+export class RuntimeMemoryProvider {
+    source;
+    id = "memory";
+    constructor(source = new CanonicalMemoryProvider()) {
+        this.source = source;
+    }
+    listTools() {
+        return [SEARCH_TOOL, READ_TOOL];
+    }
+    async callTool(name, args, context) {
+        const input = (args ?? {});
+        if (name === SEARCH_TOOL.name)
+            return this.search(context, input);
+        if (name === READ_TOOL.name)
+            return this.readTool(context, input);
+        return errorResult(`unknown memory provider tool "${name}"`);
+    }
+    async listResources(context) {
+        const refs = await this.inScopeRefs(context);
+        return refs.map((ref) => ({
+            uri: memoryUri(ref.name),
+            name: `${ref.name}.md`,
+            description: `Canonical memory ${ref.name}`,
+            mimeType: "text/markdown",
+        }));
+    }
+    async readResource(uri, context) {
+        const name = memoryNameFromUri(uri);
+        const document = await this.readDocument(name, context);
+        if (!document)
+            throw new Error(`memory "${name}" is not available to ${context.agentId}`);
+        return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text: document.content }] };
+    }
+    async inScopeRefs(context) {
+        const canonical = loadCanonicalSource(context.homeDir);
+        const refs = await this.source.list(context);
+        return refs.filter((ref) => isInScope(context.agentId, ref.scope, canonical.managedAgents));
+    }
+    async readDocument(name, context) {
+        const ref = (await this.inScopeRefs(context)).find((candidate) => candidate.name === name);
+        if (!ref)
+            return undefined;
+        const document = await this.source.read(name, context);
+        if (!document)
+            return undefined;
+        return {
+            name,
+            content: document.content,
+            fingerprint: fingerprint(document.content),
+            uri: memoryUri(name),
+            scope: "in-scope",
+            source: this.source.id,
+        };
+    }
+    async search(context, input) {
+        const query = typeof input.query === "string" ? input.query.trim().toLowerCase() : "";
+        const limit = typeof input.limit === "number" ? Math.min(50, Math.max(1, Math.floor(input.limit))) : 20;
+        const hits = [];
+        for (const ref of await this.inScopeRefs(context)) {
+            let document;
+            try {
+                document = await this.readDocument(ref.name, context);
+            }
+            catch {
+                // One unreadable memory must not hide every other memory from search.
+                continue;
+            }
+            if (!document)
+                continue;
+            if (query && !`${document.name}\n${document.content}`.toLowerCase().includes(query))
+                continue;
+            hits.push({
+                name: document.name,
+                fingerprint: document.fingerprint,
+                uri: document.uri,
+                scope: document.scope,
+                source: document.source,
+            });
+            if (hits.length >= limit)
+                break;
+        }
+        return textResult({ memories: hits });
+    }
+    async readTool(context, input) {
+        if (typeof input.name !== "string" || input.name.length === 0)
+            return errorResult('"name" is required');
+        try {
+            const document = await this.readDocument(input.name, context);
+            if (!document)
+                return errorResult(`memory "${input.name}" is not available to ${context.agentId}`);
+            return textResult(document);
+        }
+        catch (err) {
+            return errorResult(`could not read memory "${input.name}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/lib/memoryStatus.d.ts

@@ -0,0 +1,17 @@
+import type { AgentId, CanonicalSource } from "../core/types.js";
+import type { UpstreamStatus } from "./gatewayBackend.js";
+export interface MemoryReadiness {
+    backendConfigured: boolean;
+    graphPath?: string;
+    graphExists: boolean;
+    graphReadable: boolean;
+    graphWritable: boolean;
+    graphReady: boolean;
+    canonicalCount: number;
+    deliveredAgents: AgentId[];
+    writePath: "mcp" | "unavailable";
+    extractionCommand: "trellis memory extract";
+    nativeImportSupported: false;
+    upstream?: Pick<UpstreamStatus, "status" | "detail" | "remediation">;
+}
+export declare function inspectMemoryReadiness(canonical: CanonicalSource, homeDir: string, upstream?: readonly UpstreamStatus[]): MemoryReadiness;

package/dist/lib/memoryStatus.js

@@ -0,0 +1,88 @@
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { isInScope } from "../core/adapter.js";
+import { isGatewayAgent } from "../adapters/mcpPlan.js";
+function routeFor(agent, canonical) {
+    const explicit = canonical.mcp.routes?.[agent];
+    if (explicit)
+        return explicit.mode;
+    if (isGatewayAgent(agent, canonical.mcp, canonical.managedAgents))
+        return "gateway";
+    if (canonical.mcp.hub)
+        return "hub";
+    return "direct";
+}
+function memoryDeliveredTo(agent, canonical) {
+    const server = canonical.mcp.servers.memory;
+    if (!server || server.enabled === false || !isInScope(agent, server.agents, canonical.managedAgents))
+        return false;
+    const route = canonical.mcp.routes?.[agent];
+    const mode = routeFor(agent, canonical);
+    if (mode === "hub")
+        return false;
+    if (mode === "gateway" && route?.servers && !route.servers.includes("memory"))
+        return false;
+    return true;
+}
+function displayPath(raw, homeDir) {
+    if (raw === "~" || raw.startsWith("~/"))
+        return raw;
+    if (raw === homeDir || raw.startsWith(`${homeDir}/`))
+        return `~${raw.slice(homeDir.length)}`;
+    return "custom-path";
+}
+function fileState(path) {
+    const graphExists = existsSync(path);
+    const graphReadable = graphExists && (() => {
+        try {
+            accessSync(path, constants.R_OK);
+            return statSync(path).isFile();
+        }
+        catch {
+            return false;
+        }
+    })();
+    const graphWritable = (() => {
+        try {
+            let parent = graphExists ? path : dirname(path);
+            while (!existsSync(parent)) {
+                const next = dirname(parent);
+                if (next === parent)
+                    return false;
+                parent = next;
+            }
+            accessSync(parent, constants.W_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })();
+    return { graphExists, graphReadable, graphWritable, graphReady: graphWritable };
+}
+export function inspectMemoryReadiness(canonical, homeDir, upstream = []) {
+    const server = canonical.mcp.servers.memory;
+    const rawPath = server?.staticEnv?.MEMORY_FILE_PATH;
+    const backendConfigured = Boolean(server && server.enabled !== false && rawPath);
+    const graph = rawPath ? fileState(rawPath.replace(/^~(?=$|\/)/, homeDir)) : {
+        graphExists: false,
+        graphReadable: false,
+        graphWritable: false,
+        graphReady: false,
+    };
+    const memoryUpstream = upstream.find((status) => status.name === "memory");
+    const deliveredAgents = backendConfigured
+        ? canonical.managedAgents.filter((agent) => memoryDeliveredTo(agent, canonical))
+        : [];
+    return {
+        backendConfigured,
+        ...(rawPath ? { graphPath: displayPath(rawPath, homeDir) } : {}),
+        ...graph,
+        canonicalCount: canonical.memories.length,
+        deliveredAgents,
+        writePath: backendConfigured ? "mcp" : "unavailable",
+        extractionCommand: "trellis memory extract",
+        nativeImportSupported: false,
+        ...(memoryUpstream ? { upstream: { status: memoryUpstream.status, ...(memoryUpstream.detail ? { detail: memoryUpstream.detail } : {}), ...(memoryUpstream.remediation ? { remediation: memoryUpstream.remediation } : {}) } } : {}),
+    };
+}

package/dist/lib/nativeMemory.d.ts

@@ -0,0 +1,19 @@
+import type { AgentId } from "../core/types.js";
+export declare const MAX_NATIVE_MEMORY_BYTES: number;
+export type NativeMemoryStatus = "supported" | "empty" | "unsupported";
+export interface NativeMemoryCandidate {
+    sourceAgent: AgentId;
+    sourceId: string;
+    sourcePath: string;
+    displayName: string;
+    targetName: string;
+    content: string;
+}
+export interface NativeMemoryDiscovery {
+    adapter: string;
+    status: NativeMemoryStatus;
+    detail: string;
+    candidates: NativeMemoryCandidate[];
+}
+export declare function discoverNativeMemory(agent: AgentId, homeDir?: string, workspaceDir?: string, env?: NodeJS.ProcessEnv): NativeMemoryDiscovery;
+export declare function renderNativeMemory(candidate: Pick<NativeMemoryCandidate, "sourceAgent" | "sourceId" | "content">): string;