agent-trellis 0.6.3 → 0.8.0

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;

package/dist/lib/nativeMemory.js

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { slugify } from "./slug.js";
+export const MAX_NATIVE_MEMORY_BYTES = 256 * 1024;
+function claudeProjectKey(workspaceDir) {
+    const absolute = resolve(workspaceDir);
+    const normalized = absolute
+        .replace(/^[\\/]+/, "")
+        .replace(/[\\/]+/g, "-")
+        .replace(/[^A-Za-z0-9._-]/g, "-");
+    return `-${normalized}`;
+}
+function safeMarkdownFiles(root) {
+    if (!existsSync(root))
+        return [];
+    let realRoot;
+    try {
+        realRoot = realpathSync(root);
+    }
+    catch {
+        return [];
+    }
+    return readdirSync(root)
+        .filter((name) => name.endsWith(".md"))
+        .map((name) => join(root, name))
+        .filter((file) => {
+        try {
+            const realFile = realpathSync(file);
+            const rel = relative(realRoot, realFile);
+            return !rel.startsWith(`..${sep}`) && rel !== ".." && statSync(realFile).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}
+export function discoverNativeMemory(agent, homeDir = homedir(), workspaceDir = process.cwd(), env = process.env) {
+    if (agent === "codex") {
+        const codexHome = env.CODEX_HOME ? resolve(env.CODEX_HOME) : join(homeDir, ".codex");
+        const memoryRoot = join(codexHome, "memories");
+        const files = safeMarkdownFiles(memoryRoot);
+        if (files.length === 0) {
+            return {
+                adapter: "codex-local-memory",
+                status: "empty",
+                detail: `no Markdown memory files found under ${memoryRoot}; session indexes and non-Markdown state were not inspected`,
+                candidates: [],
+            };
+        }
+        const candidates = [];
+        for (const file of files) {
+            const stat = statSync(file);
+            if (stat.size > MAX_NATIVE_MEMORY_BYTES)
+                continue;
+            const content = readFileSync(file, "utf8");
+            const displayName = basename(file, ".md");
+            const targetName = `codex-${slugify(displayName)}`;
+            if (!targetName || targetName === "codex-")
+                continue;
+            candidates.push({
+                sourceAgent: agent,
+                sourceId: `codex/${displayName}`,
+                sourcePath: file,
+                displayName,
+                targetName,
+                content,
+            });
+        }
+        return {
+            adapter: "codex-local-memory",
+            status: candidates.length > 0 ? "supported" : "empty",
+            detail: candidates.length > 0
+                ? `found ${candidates.length} bounded Markdown memory file(s) under ${memoryRoot}`
+                : "Codex memory files were empty, oversized, or unsafe to read",
+            candidates,
+        };
+    }
+    if (agent !== "claude-code") {
+        return {
+            adapter: "none",
+            status: "unsupported",
+            detail: `${agent} native memory is unsupported: sessions or private stores do not have a supported Trellis adapter; no session, cache, SQLite, or credential data was read`,
+            candidates: [],
+        };
+    }
+    const projectKey = claudeProjectKey(workspaceDir);
+    const memoryRoot = join(homeDir, ".claude", "projects", projectKey, "memory");
+    const files = safeMarkdownFiles(memoryRoot);
+    if (files.length === 0) {
+        return {
+            adapter: "claude-code-project-memory",
+            status: "empty",
+            detail: `no Markdown memory files found for the exact current workspace project key "${projectKey}"`,
+            candidates: [],
+        };
+    }
+    const candidates = [];
+    for (const file of files) {
+        const stat = statSync(file);
+        if (stat.size > MAX_NATIVE_MEMORY_BYTES)
+            continue;
+        const content = readFileSync(file, "utf8");
+        const displayName = basename(file, ".md");
+        const targetName = `claude-${slugify(projectKey)}-${slugify(displayName)}`;
+        if (!targetName || targetName === "claude-")
+            continue;
+        candidates.push({
+            sourceAgent: agent,
+            sourceId: `claude-code/${projectKey}/${displayName}`,
+            sourcePath: file,
+            displayName,
+            targetName,
+            content,
+        });
+    }
+    return {
+        adapter: "claude-code-project-memory",
+        status: candidates.length > 0 ? "supported" : "empty",
+        detail: candidates.length > 0
+            ? `found ${candidates.length} bounded Markdown memory file(s) for the exact current workspace project key "${projectKey}"`
+            : "memory files were empty, oversized, or unsafe to read",
+        candidates,
+    };
+}
+export function renderNativeMemory(candidate) {
+    return `<!-- Trellis import: ${candidate.sourceAgent} / ${candidate.sourceId} -->\n\n${candidate.content.replace(/^\s+|\s+$/g, "")}\n`;
+}

package/dist/lib/runtimeControlProvider.d.ts

@@ -0,0 +1,16 @@
+import type { CallToolResult, ReadResourceResult, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { GatewayBackend } from "./gatewayBackend.js";
+import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+export declare class RuntimeControlProvider implements TrellisProvider {
+    private readonly backend;
+    private readonly trellisVersion;
+    readonly id = "runtime";
+    constructor(backend: GatewayBackend, trellisVersion?: string);
+    listTools(): Tool[];
+    callTool(name: string, _args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+    listResources(): Resource[];
+    readResource(uri: URL, context: RuntimeContext): ReadResourceResult;
+    private agents;
+    private status;
+    private instructions;
+}

package/dist/lib/runtimeControlProvider.js

@@ -0,0 +1,168 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { ALL_AGENTS, capabilityDeliveryForAgent } from "../core/types.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { isGatewayAgent } from "../adapters/mcpPlan.js";
+import * as claudeCodeProbe from "../probes/claude-code.js";
+import * as codexProbe from "../probes/codex.js";
+import * as kiroProbe from "../probes/kiro.js";
+import * as piProbe from "../probes/pi.js";
+import * as kimiCodeProbe from "../probes/kimi-code.js";
+import { TRELLIS_VERSION } from "./cliMetadata.js";
+import { inspectMemoryReadiness } from "./memoryStatus.js";
+const MAX_INSTRUCTIONS_BYTES = 256 * 1024;
+const INSTRUCTIONS_URI = "trellis://instructions/agents.md";
+const STATUS_TOOL = {
+    name: "trellis.runtime.status",
+    description: "Describe the current Agent's Trellis Runtime, managed boundary, providers, and safe MCP health summary.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+const AGENTS_TOOL = {
+    name: "trellis.agents.list",
+    description: "List installed and Trellis-managed Agents with high-level capability health; never returns credentials or private sessions.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+const INSTRUCTIONS_TOOL = {
+    name: "trellis.instructions.read",
+    description: "Read the canonical global Agent instructions as bounded Markdown.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+const PROBES = {
+    "claude-code": (homeDir) => claudeCodeProbe.probe(homeDir),
+    codex: (homeDir) => codexProbe.probe(homeDir),
+    kiro: (homeDir) => kiroProbe.probe(homeDir),
+    pi: (homeDir) => piProbe.probe(homeDir),
+    "kimi-code": (homeDir) => kimiCodeProbe.probe(homeDir),
+};
+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 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 healthFor(snapshot, managed) {
+    if (!snapshot.present)
+        return "absent";
+    if (!managed)
+        return "unmanaged";
+    if (snapshot.diagnostics.length > 0)
+        return "degraded";
+    return "healthy";
+}
+function snapshotSummary(snapshot, canonical) {
+    const managed = canonical.managedAgents.includes(snapshot.agent);
+    return {
+        id: snapshot.agent,
+        present: snapshot.present,
+        managed,
+        health: healthFor(snapshot, managed),
+        ...(snapshot.version ? { version: snapshot.version } : {}),
+        runtimeDelivery: capabilityDeliveryForAgent(snapshot.agent, canonical.mcp),
+        mcpRoute: routeFor(snapshot.agent, canonical),
+        skillCount: snapshot.skillRoots.reduce((count, root) => count + root.skills.length, 0),
+        mcpServerCount: snapshot.mcpServers.length,
+        instructions: { present: snapshot.instructionsFile !== undefined, native: true },
+        diagnostics: snapshot.diagnostics,
+    };
+}
+async function probeAgents(homeDir) {
+    const results = await Promise.allSettled(ALL_AGENTS.map((agent) => PROBES[agent](homeDir)));
+    return results.map((result, index) => result.status === "fulfilled"
+        ? result.value
+        : { agent: ALL_AGENTS[index], present: false, skillRoots: [], mcpServers: [], diagnostics: [`probe failed: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`] });
+}
+function safeInstructions(homeDir, file) {
+    const canonicalRoot = realpathSync(join(homeDir, ".trellis"));
+    const realFile = realpathSync(file);
+    const rel = relative(canonicalRoot, realFile);
+    if (rel.startsWith(`..${sep}`) || rel === "..")
+        throw new Error("canonical instructions file is outside ~/.trellis");
+    const stat = statSync(realFile);
+    if (!stat.isFile() || stat.size > MAX_INSTRUCTIONS_BYTES)
+        throw new Error(`instructions exceed the ${MAX_INSTRUCTIONS_BYTES}-byte provider limit`);
+    return readFileSync(realFile, "utf8");
+}
+export class RuntimeControlProvider {
+    backend;
+    trellisVersion;
+    id = "runtime";
+    constructor(backend, trellisVersion = TRELLIS_VERSION) {
+        this.backend = backend;
+        this.trellisVersion = trellisVersion;
+    }
+    listTools() {
+        return [STATUS_TOOL, AGENTS_TOOL, INSTRUCTIONS_TOOL];
+    }
+    async callTool(name, _args, context) {
+        if (name === STATUS_TOOL.name)
+            return textResult(await this.status(context));
+        if (name === AGENTS_TOOL.name)
+            return textResult(await this.agents(context));
+        if (name === INSTRUCTIONS_TOOL.name) {
+            try {
+                return textResult(this.instructions(context));
+            }
+            catch (err) {
+                return errorResult(`could not read canonical instructions: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return errorResult(`unknown control-plane tool "${name}"`);
+    }
+    listResources() {
+        return [{ uri: INSTRUCTIONS_URI, name: "agents.md", description: "Canonical global Agent instructions", mimeType: "text/markdown" }];
+    }
+    readResource(uri, context) {
+        if (uri.toString() !== INSTRUCTIONS_URI)
+            throw new Error(`unsupported instructions resource URI "${uri.toString()}"`);
+        const value = this.instructions(context);
+        return { contents: [{ uri: INSTRUCTIONS_URI, mimeType: "text/markdown", text: value.content }] };
+    }
+    async agents(context) {
+        const canonical = loadCanonicalSource(context.homeDir);
+        const snapshots = await probeAgents(context.homeDir);
+        return { agents: snapshots.map((snapshot) => snapshotSummary(snapshot, canonical)), source: "trellis" };
+    }
+    async status(context) {
+        const canonical = loadCanonicalSource(context.homeDir);
+        const snapshots = await probeAgents(context.homeDir);
+        const current = snapshots.find((snapshot) => snapshot.agent === context.agentId);
+        const currentSummary = current ? snapshotSummary(current, canonical) : { id: context.agentId, present: false };
+        const route = routeFor(context.agentId, canonical);
+        const upstream = this.backend.listStatus?.() ?? [];
+        const unhealthy = upstream.filter((status) => status.status !== "ready");
+        const memory = inspectMemoryReadiness(canonical, context.homeDir, upstream);
+        return {
+            agent: currentSummary,
+            runtime: { trellisVersion: this.trellisVersion, edge: "gateway", route },
+            providers: {
+                skills: { available: true, canonicalCount: canonical.skills.length },
+                memory: { available: true, ...memory },
+                instructions: { available: existsSync(canonical.instructionsFile), native: true, runtimeReadable: true },
+                mcp: { available: true, upstreamCount: upstream.length, unhealthyCount: unhealthy.length },
+                tasks: { available: true, mutationRequiresConfirmation: true, launchesAgents: false },
+            },
+            upstream,
+            agents: snapshots.map((snapshot) => snapshotSummary(snapshot, canonical)),
+            source: "trellis",
+        };
+    }
+    instructions(context) {
+        const canonical = loadCanonicalSource(context.homeDir);
+        const content = safeInstructions(context.homeDir, canonical.instructionsFile);
+        return { name: "agents.md", content, fingerprint: createHash("sha256").update(content).digest("hex"), source: "canonical" };
+    }
+}

package/dist/lib/secretEnv.d.ts

@@ -9,6 +9,7 @@
  * this narrow need requires (design.md D4).
  */
 import type { SecretsPolicy } from "../core/types.js";
+import type { BackupSession } from "./backup.js";
 export declare function parseDotenv(content: string): Record<string, string>;
 /**
  * `policy.envFile` set: it is the SOLE source — a name absent from it
@@ -17,3 +18,19 @@ export declare function parseDotenv(content: string): Record<string, string>;
  * reads `process.env` directly, identical to every pre-existing caller.
  */
 export declare function resolveSecretEnv(names: string[], policy: SecretsPolicy): Record<string, string | undefined>;
+export type WriteLocalSecretOutcome = "created" | "already-present" | "conflict";
+/**
+ * `trellis migrate`'s static-env secret extraction
+ * (trellis-migrate-extract-static-env-secrets design.md D4) — appends
+ * one `NAME=value` line to a dotenv-format file in exactly the shape
+ * `parseDotenv` above already reads, creating the file (and its parent
+ * directory) if neither exists yet. Idempotent, the same three-way
+ * split every other Trellis writer uses: the name is absent (create),
+ * already present with the identical value (no-op — re-running migrate
+ * must not duplicate the line), or already present with a *different*
+ * value (conflict, left untouched — the file may hold a value the user
+ * already rotated by hand since the last run; silently overwriting it
+ * would be exactly the kind of value-clobbering this whole feature
+ * exists to prevent, just relocated to a new file).
+ */
+export declare function writeLocalSecretValue(path: string, name: string, value: string, backup?: BackupSession): WriteLocalSecretOutcome;