agent-trellis 0.7.0 → 0.8.0

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
@@ -32,4 +33,4 @@ export type WriteLocalSecretOutcome = "created" | "already-present" | "conflict"
  * 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): WriteLocalSecretOutcome;
+export declare function writeLocalSecretValue(path: string, name: string, value: string, backup?: BackupSession): WriteLocalSecretOutcome;

package/dist/lib/secretEnv.js

@@ -59,7 +59,7 @@ export function resolveSecretEnv(names, policy) {
  * would be exactly the kind of value-clobbering this whole feature
  * exists to prevent, just relocated to a new file).
  */
-export function writeLocalSecretValue(path, name, value) {
+export function writeLocalSecretValue(path, name, value, backup) {
     const existingContent = existsSync(path) ? readFileSync(path, "utf-8") : "";
     const existing = parseDotenv(existingContent);
     if (Object.hasOwn(existing, name)) {
@@ -67,6 +67,10 @@ export function writeLocalSecretValue(path, name, value) {
     }
     mkdirSync(dirname(path), { recursive: true });
     const separator = existingContent.length > 0 && !existingContent.endsWith("\n") ? "\n" : "";
-    appendFileSync(path, `${separator}${name}=${value}\n`);
+    const next = `${existingContent}${separator}${name}=${value}\n`;
+    if (backup)
+        backup.writeFile(path, next);
+    else
+        appendFileSync(path, `${separator}${name}=${value}\n`);
     return "created";
 }

package/dist/lib/skillProvider.d.ts

@@ -0,0 +1,13 @@
+import type { Resource, ReadResourceResult, Tool, CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+export declare class SkillProvider implements TrellisProvider {
+    readonly id = "skills";
+    listTools(): Tool[];
+    callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+    listResources(context: RuntimeContext): Resource[];
+    readResource(uri: URL, context: RuntimeContext): ReadResourceResult;
+    private search;
+    private readSkill;
+    private readFile;
+    private readBoundedFile;
+}

package/dist/lib/skillProvider.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { resolve, relative, sep } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { isInScope } from "../core/adapter.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveScope } from "../core/types.js";
+const MAX_FILE_BYTES = 256 * 1024;
+const SKILL_RESOURCE_PREFIX = "trellis://skills/";
+const SEARCH_TOOL = {
+    name: "trellis.skills.search",
+    description: "Search in-scope Trellis skills by name or description, then read one selected skill 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.skills.read",
+    description: "Read the SKILL.md instructions for one in-scope Trellis skill.",
+    inputSchema: {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+const READ_FILE_TOOL = {
+    name: "trellis.skills.read_file",
+    description: "Read one bounded, non-secret supporting file under an in-scope skill directory.",
+    inputSchema: {
+        type: "object",
+        properties: { name: { type: "string" }, relativePath: { type: "string" } },
+        required: ["name", "relativePath"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+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 frontmatter(content) {
+    if (!content.startsWith("---"))
+        return {};
+    const end = content.indexOf("\n---", 3);
+    if (end < 0)
+        return {};
+    try {
+        const parsed = parseYaml(content.slice(3, end));
+        return {
+            name: typeof parsed?.name === "string" ? parsed.name : undefined,
+            description: typeof parsed?.description === "string" ? parsed.description : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function fingerprint(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function isSecretLikePath(path) {
+    const normalized = path.toLowerCase();
+    return normalized.includes(".env") || normalized.includes("secret") || normalized.endsWith("servers.local.env");
+}
+function skillFor(canonical, agentId, name) {
+    const skill = canonical.skills.find((candidate) => candidate.name === name);
+    if (!skill || !hasSkillDocument(skill) || !isInScope(agentId, skill.scope, canonical.managedAgents))
+        return undefined;
+    return skill;
+}
+function hasSkillDocument(skill) {
+    try {
+        return statSync(resolve(skill.dir, "SKILL.md")).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function skillUri(name) {
+    return `${SKILL_RESOURCE_PREFIX}${encodeURIComponent(name)}/SKILL.md`;
+}
+function skillMetadata(skill, canonical, agentId, content) {
+    const metadata = frontmatter(content);
+    return {
+        name: skill.name,
+        description: metadata.description ?? "",
+        fingerprint: fingerprint(content),
+        uri: skillUri(skill.name),
+        scope: resolveScope(skill.scope, canonical.managedAgents).includes(agentId) ? "in-scope" : "out-of-scope",
+        source: "canonical",
+    };
+}
+export class SkillProvider {
+    id = "skills";
+    listTools() {
+        return [SEARCH_TOOL, READ_TOOL, READ_FILE_TOOL];
+    }
+    async callTool(name, args, context) {
+        const canonical = loadCanonicalSource(context.homeDir);
+        const input = (args ?? {});
+        if (name === SEARCH_TOOL.name)
+            return this.search(canonical, context.agentId, input);
+        if (name === READ_TOOL.name)
+            return this.readSkill(canonical, context.agentId, input);
+        if (name === READ_FILE_TOOL.name)
+            return this.readFile(canonical, context.agentId, input);
+        return errorResult(`unknown skill provider tool "${name}"`);
+    }
+    listResources(context) {
+        const canonical = loadCanonicalSource(context.homeDir);
+        return canonical.skills
+            .filter((skill) => hasSkillDocument(skill) && isInScope(context.agentId, skill.scope, canonical.managedAgents))
+            .map((skill) => ({
+            uri: skillUri(skill.name),
+            name: `${skill.name}/SKILL.md`,
+            description: `Instructions for the ${skill.name} skill`,
+            mimeType: "text/markdown",
+        }));
+    }
+    readResource(uri, context) {
+        if (uri.protocol !== "trellis:" || uri.hostname !== "skills") {
+            throw new Error(`unsupported skill resource URI "${uri.toString()}"`);
+        }
+        const segments = uri.pathname.split("/").filter(Boolean).map((segment) => decodeURIComponent(segment));
+        if (segments.length !== 2 || segments[1] !== "SKILL.md") {
+            throw new Error(`unsupported skill resource URI "${uri.toString()}"`);
+        }
+        const canonical = loadCanonicalSource(context.homeDir);
+        const skill = skillFor(canonical, context.agentId, segments[0]);
+        if (!skill)
+            throw new Error(`skill "${segments[0]}" is not available to ${context.agentId}`);
+        const content = this.readBoundedFile(resolve(skill.dir, "SKILL.md"), skill.dir);
+        return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text: content }] };
+    }
+    search(canonical, agentId, 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 results = canonical.skills
+            .filter((skill) => isInScope(agentId, skill.scope, canonical.managedAgents))
+            .map((skill) => {
+            let content;
+            try {
+                content = this.readBoundedFile(resolve(skill.dir, "SKILL.md"), skill.dir);
+            }
+            catch {
+                return undefined;
+            }
+            return { ...skillMetadata(skill, canonical, agentId, content), dir: skill.dir };
+        })
+            .filter((skill) => skill !== undefined)
+            .filter((skill) => !query || `${skill.name} ${skill.description}`.toLowerCase().includes(query))
+            .slice(0, limit)
+            .map(({ dir: _dir, ...result }) => result);
+        return textResult({ skills: results });
+    }
+    readSkill(canonical, agentId, input) {
+        if (typeof input.name !== "string" || input.name.length === 0)
+            return errorResult('"name" is required');
+        const skill = skillFor(canonical, agentId, input.name);
+        if (!skill)
+            return errorResult(`skill "${input.name}" is not available to ${agentId}`);
+        const path = resolve(skill.dir, "SKILL.md");
+        const content = this.readBoundedFile(path, skill.dir);
+        return textResult({ ...skillMetadata(skill, canonical, agentId, content), content });
+    }
+    readFile(canonical, agentId, input) {
+        if (typeof input.name !== "string" || typeof input.relativePath !== "string")
+            return errorResult('"name" and "relativePath" are required');
+        const skill = skillFor(canonical, agentId, input.name);
+        if (!skill)
+            return errorResult(`skill "${input.name}" is not available to ${agentId}`);
+        if (input.relativePath.length === 0 || input.relativePath.includes("\0") || isSecretLikePath(input.relativePath)) {
+            return errorResult("supporting file path is not allowed");
+        }
+        try {
+            const path = resolve(skill.dir, input.relativePath);
+            const root = realpathSync(skill.dir);
+            const realPath = realpathSync(path);
+            const rel = relative(root, realPath);
+            if (rel.startsWith(`..${sep}`) || rel === ".." || !existsSync(realPath) || !statSync(realPath).isFile()) {
+                return errorResult("supporting file is outside the skill root");
+            }
+            return textResult({ name: skill.name, relativePath: rel, source: "canonical-skill-supporting-file", content: this.readBoundedFile(realPath, root) });
+        }
+        catch (err) {
+            return errorResult(`could not read supporting file: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    readBoundedFile(path, root) {
+        if (isSecretLikePath(path))
+            throw new Error("secret-like files are not readable through the skill provider");
+        const rootPath = realpathSync(root);
+        const realPath = realpathSync(path);
+        const rel = relative(rootPath, realPath);
+        if (rel.startsWith(`..${sep}`) || rel === "..")
+            throw new Error("file is outside the skill root");
+        const stat = statSync(realPath);
+        if (!stat.isFile() || stat.size > MAX_FILE_BYTES)
+            throw new Error(`file exceeds the ${MAX_FILE_BYTES}-byte provider limit`);
+        return readFileSync(realPath, "utf8");
+    }
+}

package/dist/lib/taskProvider.d.ts

@@ -0,0 +1,7 @@
+import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+export declare class TaskProvider implements TrellisProvider {
+    readonly id = "tasks";
+    listTools(): Tool[];
+    callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+}

package/dist/lib/taskProvider.js

@@ -0,0 +1,43 @@
+import { claimTask, createTask, handoffTask, listTasks, readTask, updateTask } from "./taskStore.js";
+const LIST = { name: "trellis.tasks.list", description: "List safe Trellis handoff tasks.", inputSchema: { type: "object", properties: { status: { type: "string" }, toAgent: { type: "string" } }, additionalProperties: false }, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false } };
+const READ = { name: "trellis.tasks.read", description: "Read one Trellis handoff task and its audit history.", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false }, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false } };
+const CREATE = { name: "trellis.tasks.create", description: "Create a safe durable handoff task. Requires explicit confirm=true and never launches another Agent.", inputSchema: { type: "object", properties: { objective: { type: "string" }, toAgent: { type: "string" }, context: { type: "object" }, constraints: { type: "array", items: { type: "string" } }, confirm: { type: "boolean" } }, required: ["objective", "confirm"], additionalProperties: false }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
+const CLAIM = { name: "trellis.tasks.claim", description: "Claim one pending handoff task with an exclusive lease. Requires explicit confirm=true.", inputSchema: { type: "object", properties: { id: { type: "string" }, leaseMs: { type: "number" }, confirm: { type: "boolean" } }, required: ["id", "confirm"], additionalProperties: false }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
+const UPDATE = { name: "trellis.tasks.update", description: "Update a claimed task status without launching another Agent. Requires explicit confirm=true.", inputSchema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" }, note: { type: "string" }, result: { type: "string" }, confirm: { type: "boolean" } }, required: ["id", "status", "confirm"], additionalProperties: false }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
+const HANDOFF = { name: "trellis.tasks.handoff", description: "Hand a task to another managed Agent as data only. Requires explicit confirm=true.", inputSchema: { type: "object", properties: { id: { type: "string" }, toAgent: { type: "string" }, note: { type: "string" }, confirm: { type: "boolean" } }, required: ["id", "toAgent", "confirm"], additionalProperties: false }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
+function result(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: value };
+}
+function failure(error) {
+    return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true };
+}
+export class TaskProvider {
+    id = "tasks";
+    listTools() { return [LIST, READ, CREATE, CLAIM, UPDATE, HANDOFF]; }
+    async callTool(name, args, context) {
+        const input = (args ?? {});
+        try {
+            if (name === LIST.name) {
+                const status = input.status;
+                const toAgent = input.toAgent;
+                return result({ tasks: listTasks(context.homeDir, { status, toAgent }) });
+            }
+            if (name === READ.name)
+                return result(readTask(context.homeDir, String(input.id ?? "")));
+            if (input.confirm !== true)
+                return failure(`task mutation "${name}" requires confirm=true; no Agent is launched automatically`);
+            if (name === CREATE.name)
+                return result(createTask(context.homeDir, { objective: String(input.objective ?? ""), fromAgent: context.agentId, ...(input.toAgent ? { toAgent: input.toAgent } : {}), ...(input.context ? { context: input.context } : {}), ...(input.constraints ? { constraints: input.constraints } : {}) }));
+            if (name === CLAIM.name)
+                return result(claimTask(context.homeDir, String(input.id ?? ""), context.agentId, input.leaseMs));
+            if (name === UPDATE.name)
+                return result(updateTask(context.homeDir, String(input.id ?? ""), context.agentId, input.status, input.note, input.result));
+            if (name === HANDOFF.name)
+                return result(handoffTask(context.homeDir, String(input.id ?? ""), context.agentId, input.toAgent, input.note));
+            return failure(`unknown task tool "${name}"`);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    }
+}