@amaster.ai/dsh-subagent-filesystem 0.0.0-stage → 0.1.23

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugins contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# dsh-subagent-filesystem
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Markdown roles for dsh
+
+![dsh-subagent-filesystem preview](./preview.png)
+
+Discover specialist roles from the agent workspace's `agents/*.md` and expose named delegation tools. Each Markdown body becomes a separate child system section, preserving Harness instructions, the application persona, and native permissions. The delegated task remains user content. Files are read exclusively through the caller's scoped `ctx.fs`, including remote and sandbox providers, with no host-filesystem fallback.
+
+## Install and configure
+
+```sh
+dsh plugin --profile my-agent add @amaster.ai/dsh-subagent-filesystem
+```
+
+Enable the bundle in the profile's `cordis.patch.yml`:
+
+```yaml
+- id: subagent-filesystem
+  config:
+    enabled: true
+    root: agents
+```
+
+Disabled by default. `root` defaults to `agents`, relative to the agent's initial workspace directory; sandbox deployments can explicitly select `/agents`. Discovery scans direct `*.md` children only. A missing root produces an empty catalog. Files are loaded when the agent is created; create a new agent to pick up changes. Watching and hot reload are outside the initial scope.
+
+Requires the `fs`, `tools`, `subagents`, `systemPrompt`, and `sessionQuery` services, plus the native in-process provider registered as `spawn`. The standard headless profile supplies these capabilities. DSH peer floor: `>=0.2.0-rc.1`; tested DSH: `0.2.0-rc.2`; tested Cordis: `4.0.4`.
+
+## Definition format
+
+`agents/inventory-analyst.md`:
+
+```markdown
+---
+name: inventory-analyst
+description: Investigate inventory discrepancies and explain their causes.
+---
+You are the inventory analyst. Compare posted movements with current balances,
+identify discrepancies, and report evidence before recommending changes.
+Read references/inventory-rules.md relative to this definition before analysis.
+```
+
+Only `name` and `description` are supported in YAML frontmatter. Names must be lowercase kebab-case, start with a letter, and contain at most 55 characters. Description and body must be nonempty. Definitions must be valid UTF-8 and at most 1 MiB. Unsupported fields, duplicate YAML keys, duplicate role names, and tool-name collisions fail that agent's catalog load with a `[dsh-subagent-filesystem]` error. No partial catalog is published; existing application tools are preserved.
+
+`{{…}}` in the body stays literal. Child instructions include the definition's resource directory. The child opens supporting references, scripts, and assets with its own tools, resolving relative paths against that directory. This plugin does not download or execute resources.
+
+## Delegation
+
+The example exposes `subagent_inventory_analyst`; its description tells the parent when to delegate.
+
+| Parameter | Meaning |
+| --- | --- |
+| `prompt` | Required: a complete, self-contained task delivered as the child's user message |
+| `description` | Required: the native subagent's short task label |
+| `run_in_background` | Default false: wait for a report; true: return a continuable child id |
+
+Background children use native completion notifications and `send_message` for follow-up. Native subagent services retain model defaults, delegation depth, sandbox boundaries, and approval rules. Definition files cannot override models, tools, or permissions. Foreground failures become tool errors; accepted runs always reach native cleanup.
+
+Named tools belong only to the consuming parent agent. They do not leak into other agents or workspaces, or automatically copy to children. A `subagent-filesystem/role` session event stores the child's role instructions and resource path. Cold restoration reinstalls the original snapshot rather than changing an existing role when its source file changes. Protect these instruction snapshots through the consuming application's existing session storage and access controls.
+
+Unloading cancels outstanding delegations, removes registrations and listeners, and releases background children started by the plugin. Role restoration requires the plugin to remain enabled. The initial version supports native in-process spawn; external ACP/Codex/Claude providers and application configuration downloads are outside its scope.
+
+## Tests
+
+```sh
+pnpm --filter @amaster.ai/dsh-subagent-filesystem test
+pnpm --filter @amaster.ai/dsh-subagent-filesystem typecheck
+pnpm --filter @amaster.ai/dsh-subagent-filesystem build
+```
+
+`.github/scripts/integration/dsh-subagent-filesystem.mjs` automatically joins the repository E2E matrix. It installs the packed bundle, starts real dsh, delegates through the integration model, and verifies the actual child system instructions, user task, and resource-file evidence. A local forwarding gateway inspects protocol requests, so system/user separation is verified independently of the model's claims.
+
+Required: `DSH_PKG_TARBALL`, `DSH_INTEGRATION_BASE_URL`, and `DSH_INTEGRATION_API_KEY`. Optional: `DSH_CLI`, `DSH_HOME`, and `DSH_INTEGRATION_MODEL`. For local development, set `DSH_SUBAGENT_E2E_FAKE=1` to use deterministic Messages responses while still running real dsh, native children, and file tools. This mode does not validate real-model behavior.

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: subagent-filesystem
+      name: '@amaster.ai/dsh-subagent-filesystem'

package/lib/index.js

@@ -0,0 +1,239 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { dirname } from 'node:path';
+import { settleRun } from '@deepseek-ai/dsh-subagent';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import Schema from '@deepseek-ai/schemastery';
+import { parseDocument } from 'yaml';
+export const name = 'dsh-subagent-filesystem';
+export const inject = ['fs', 'tools', 'subagents', 'systemPrompt', 'sessionQuery'];
+export const Config = Schema.object({
+    enabled: Schema.boolean().default(false),
+    root: Schema.string().default('agents'),
+});
+class DefinitionError extends Error {
+}
+function assertRole(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new DefinitionError('Invalid role snapshot');
+    }
+    const { version, name, description, body, path } = value;
+    if (version !== 1)
+        throw new DefinitionError('Unsupported role snapshot version');
+    if (typeof name !== 'string' ||
+        !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(name) ||
+        name.length > 55) {
+        throw new DefinitionError('Expected a kebab-case name of at most 55 characters');
+    }
+    if (typeof description !== 'string' ||
+        !description.trim() ||
+        typeof body !== 'string' ||
+        !body.trim() ||
+        typeof path !== 'string' ||
+        !path) {
+        throw new DefinitionError('Expected a nonempty description, role body and definition path');
+    }
+    if (Buffer.byteLength(body) + Buffer.byteLength(description) > 1024 * 1024) {
+        throw new DefinitionError('Role definition exceeds 1 MiB');
+    }
+}
+function parseRole(text, path) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (!match)
+        throw new DefinitionError('Expected YAML frontmatter');
+    const doc = parseDocument(match[1]);
+    if (doc.errors.length)
+        throw new DefinitionError('Invalid YAML frontmatter');
+    const metadata = doc.toJS({ maxAliasCount: 0 });
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+        throw new DefinitionError('Expected name and description');
+    }
+    if (Object.keys(metadata).some((key) => key !== 'name' && key !== 'description')) {
+        throw new DefinitionError('Only name and description are supported');
+    }
+    const { name, description } = metadata;
+    const body = text.slice(match[0].length).trim();
+    const role = { version: 1, name, description, body, path };
+    assertRole(role);
+    return { ...role, description: role.description.trim() };
+}
+export function apply(ctx, config) {
+    if (!config.enabled)
+        return;
+    if (!(config.root ?? 'agents').trim())
+        throw new Error('root must not be empty');
+    const lifecycle = new AbortController();
+    const delegation = new AsyncLocalStorage();
+    const registrations = new Map();
+    const children = new Map();
+    const pending = new Set();
+    function track(work) {
+        pending.add(work);
+        void work.finally(() => pending.delete(work)).catch(() => { });
+        return work;
+    }
+    const own = (agent, dispose) => {
+        const rows = registrations.get(agent) ?? [];
+        rows.push(dispose);
+        registrations.set(agent, rows);
+    };
+    const remove = (agent) => {
+        for (const dispose of registrations.get(agent) ?? [])
+            dispose();
+        registrations.delete(agent);
+        children.delete(agent);
+    };
+    // Verified against dsh-agent@0.2.0-rc.1: this serial event precedes the first prompt.
+    ctx.on('agent/created', ({ agent, source, signal }) => {
+        return track(initialize(agent, source, signal)).then(() => undefined, (error) => {
+            console.error('[dsh-subagent-filesystem] Child role initialization failed');
+            throw error;
+        });
+    });
+    ctx.on('agent/disposed', ({ agent }) => remove(agent));
+    ctx.effect(() => async () => {
+        lifecycle.abort();
+        await Promise.allSettled([...pending]);
+        const released = await Promise.allSettled([...children].map(([parent, ids]) => ctx.subagents.drainContinuableChildren(parent, ids)));
+        for (const result of released) {
+            if (result.status === 'rejected')
+                console.error('[dsh-subagent-filesystem] Child cleanup failed');
+        }
+        for (const agent of registrations.keys())
+            remove(agent);
+    });
+    async function initialize(agent, source, requestedSignal) {
+        const signal = AbortSignal.any([
+            lifecycle.signal,
+            ...(requestedSignal ? [requestedSignal] : []),
+        ]);
+        const inherited = delegation.getStore();
+        if (agent.session.header.parentSession) {
+            let role;
+            if (inherited?.parent.id === agent.session.header.parentSession) {
+                role = inherited.role;
+                agent.session.append('subagent-filesystem/role', role);
+            }
+            else if (source !== 'startup') {
+                const log = await agent.ctx.get('sessionQuery').readSession(agent.id);
+                for (const event of log.events.slice(log.inheritedEventCount)) {
+                    if (event.type === 'subagent-filesystem/role') {
+                        assertRole(event.data);
+                        role = event.data;
+                    }
+                }
+                const parent = ctx.get('agents')?.get(agent.session.header.parentSession);
+                if (role && parent) {
+                    const ids = children.get(parent) ?? [];
+                    if (!ids.includes(agent.id))
+                        ids.push(agent.id);
+                    children.set(parent, ids);
+                }
+            }
+            if (role) {
+                signal.throwIfAborted();
+                own(agent, agent.ctx.get('systemPrompt').section({
+                    name: 'subagent-filesystem:role',
+                    order: agent.ctx.get('systemPrompt').getSectionOrder('DEPLOYMENT_PERSONA_PREFIX') + 1,
+                    interpolate: false,
+                    text: `${role.body}\n\nRole definition: ${JSON.stringify(role.path)}. Resolve supporting references and scripts relative to ${JSON.stringify(dirname(role.path))} in your filesystem.`,
+                }));
+            }
+            return;
+        }
+        try {
+            const cwd = agent.session.header.cwd;
+            if (!cwd)
+                throw new Error('The agent needs a workspace directory');
+            const fs = agent.ctx.get('fs');
+            const root = await fs.resolve(config.root ?? 'agents', { cwd, signal });
+            const info = await fs.stat(root, signal);
+            if (!info)
+                return;
+            if (info.type !== 'directory')
+                throw new DefinitionError('root must be a directory');
+            const roles = [];
+            const names = new Set();
+            for (const entry of await fs.listDir(root, signal)) {
+                if (entry.type !== 'file' || !entry.name.endsWith('.md'))
+                    continue;
+                if ((entry.size ?? 0) > 1024 * 1024)
+                    throw new DefinitionError('Role file exceeds 1 MiB');
+                const bytes = await fs.readBytes(entry.target, signal, 1024 * 1024);
+                const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+                const role = parseRole(text, entry.target.displayPath);
+                const toolName = `subagent_${role.name.replaceAll('-', '_')}`;
+                if (names.has(toolName) || agent.ctx.get('tools').get(toolName, agent))
+                    throw new DefinitionError('Duplicate role or tool name');
+                names.add(toolName);
+                roles.push(role);
+            }
+            signal.throwIfAborted();
+            for (const role of roles) {
+                own(agent, agent.ctx.get('tools').register(defineTool({
+                    name: `subagent_${role.name.replaceAll('-', '_')}`,
+                    description: `${role.description} Delegate a self-contained task to this specialist. Foreground calls return its report; background calls return a continuable child id.`,
+                    parameters: {
+                        prompt: {
+                            type: 'string',
+                            required: true,
+                            description: 'The complete delegated task.',
+                        },
+                        description: { type: 'string', required: true, description: 'Short task label.' },
+                        run_in_background: {
+                            type: 'boolean',
+                            description: 'Return a child id instead of waiting. Defaults to false; use send_message for follow-up.',
+                        },
+                    },
+                    output: {
+                        schema: { type: 'string' },
+                        render: (_args, value) => [{ type: 'text', text: value }],
+                    },
+                    isConcurrencySafe: () => true,
+                    async execute(args, exec) {
+                        if (exec.agent !== agent)
+                            throw new Error('Role belongs to a different agent');
+                        const provider = agent.ctx.get('subagents').getProvider('spawn');
+                        if (!provider?.prepareContinuable || provider.inheritsParentContext)
+                            throw new Error('Roles require the native in-process spawn provider');
+                        const signal = AbortSignal.any([exec.signal, lifecycle.signal]);
+                        signal.throwIfAborted();
+                        return track(delegation.run({ parent: agent, role }, async () => {
+                            const request = {
+                                parent: agent,
+                                prompt: [{ type: 'text', text: args.prompt }],
+                                maxDepth: agent.ctx.get('subagents').resolveMaxDepth(),
+                            };
+                            if (args.run_in_background) {
+                                const child = await agent.ctx.get('subagents').startContinuable({
+                                    provider: 'spawn',
+                                    label: args.description,
+                                    request,
+                                    signal,
+                                });
+                                const ids = children.get(agent) ?? [];
+                                ids.push(child.childId);
+                                children.set(agent, ids);
+                                return `started subagent ${child.childId}; use send_message to continue it`;
+                            }
+                            const outcome = await settleRun(await agent.ctx
+                                .get('subagents')
+                                .start('spawn', { ...request, label: args.description, signal }));
+                            if (outcome.status !== 'completed')
+                                throw new Error(outcome.detail ?? `Subagent ${outcome.status}`);
+                            return outcome.result ?? '';
+                        }));
+                    },
+                })));
+            }
+        }
+        catch (error) {
+            remove(agent);
+            if (!signal.aborted)
+                console.error('[dsh-subagent-filesystem] Role discovery failed', error instanceof DefinitionError
+                    ? error.message
+                    : error instanceof Error
+                        ? error.name
+                        : 'Error');
+        }
+    }
+}

package/lib/types/index.d.ts

@@ -0,0 +1,29 @@
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+export declare const name = "dsh-subagent-filesystem";
+export declare const inject: string[];
+export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+    enabled: Schema<boolean, boolean, "defined">;
+    root: Schema<string, string, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: Schema<boolean, boolean, "defined">;
+    root: Schema<string, string, "defined">;
+}>>, "plain">;
+export interface Config {
+    enabled: boolean;
+    root?: string;
+}
+interface Role {
+    version: 1;
+    name: string;
+    description: string;
+    body: string;
+    path: string;
+}
+declare module '@deepseek-ai/dsh-session' {
+    interface SessionEventMap {
+        'subagent-filesystem/role': Role;
+    }
+}
+export declare function apply(ctx: Context, config: Config): void;
+export {};

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@amaster.ai/dsh-subagent-filesystem",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.23",
+  "description": "Discover Markdown specialist roles through the DSH filesystem and delegate through native in-process subagents.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "preview.png"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TGYD-helige/dsh-plugins.git",
+    "directory": "packages/dsh-subagent-filesystem"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "yaml": "^2.8.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-agent": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-fs": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-session-query": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-subagent": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-system-prompt": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-fs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-query": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": "^20.19 || ^22.12 || >=24.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }