@zhin.js/agent-feature 1.0.13 → 1.1.1

package/README.md

@@ -1,40 +1,59 @@
 # @zhin.js/agent-feature
 
-下一代 Markdown Agent Feature。它从 `agents/<name>.agent.md` 构造 immutable Agent definition，不读取旧分形 `agent.ts`、`instructions.md` 或模块级 SubAgent registry。
+目录化子 Agent Feature。主 Agent 使用插件根目录的标准 `AGENTS.md`；命名子 Agent 使用 `agents/<name>/` 自包含模块。运行时只识别 `agent.json`，不扫描单文件 `.agent.md`、`agent.ts` 或 `instructions.md`。
 
 ## 目录约定
 
 ```text
-agents/
-├── planner.agent.md
-└── reviewer.agent.md
+my-plugin/
+├── AGENTS.md
+└── agents/
+    └── backend-engineer/
+        ├── agent.json
+        ├── system.md
+        ├── boundaries.md
+        ├── conventions.md
+        ├── workflows/
+        │   └── create-api.md
+        ├── tools/
+        │   └── schema-validator/
+        │       └── index.ts
+        ├── skills/
+        │   └── db-migration/
+        │       ├── SKILL.md
+        │       └── tools/
+        │           └── schema-check/
+        │               └── index.ts
+        ├── hooks/
+        │   └── audit/
+        │       └── index.ts
+        └── knowledge/
+            └── internal-architecture.md
 ```
 
-Agent 目录只允许一级、精确 `.agent.md` 后缀。`planner.agent.md` 的 local name 是 `planner`；child Plugin 的 qualified name 自动包含 Plugin instance path。
-
-## Markdown 契约
-
-```markdown
-# Planner
-
-Break the request into verifiable steps. Prefer reversible actions.
+`agents/<name>` 必须使用小写 kebab-case。四个核心文件缺一不可；`workflows/`、`tools/`、`skills/`、`hooks/`、`knowledge/` 可省略。`entry_points` 决定提示词的组合顺序，并且必须包含三个核心 Markdown 文件。
+
+```json
+{
+  "name": "Backend Engineer Agent",
+  "version": "1.0.0",
+  "description": "负责后端业务逻辑与 API 设计",
+  "trigger_rules": {
+    "file_patterns": ["src/backend/**", "database/**"],
+    "keywords": ["api", "service", "migration"]
+  },
+  "entry_points": ["system.md", "boundaries.md", "conventions.md"],
+  "permissions": ["role(developer)"]
+}
 ```
 
-完整 Markdown 是 `instructions` SSOT。首个 heading 作为 description；没有 heading 时使用文件 identity。Feature 不绑定模型、system prompt 模板、tool policy 或 session store，这些属于 orchestrator adapter。
-
-单文件插件可用 `setup({ addAgent })` 注册 Markdown Agent，例如
-`addAgent('planner', '# Planner\n\nBreak work into verifiable steps.')`；目录模式和 setup
-模式共用 AgentIndex。
-
-## Projection
-
-`AgentIndex.list()` 返回全树 qualified descriptors；`visible(owner)` 和 `get(owner, name)` 使用 nearest-owner inheritance。不同 Plugin owner 的同名 Agent 不通过扫描顺序覆盖。
+`system.md` 定义身份与任务，`boundaries.md` 定义权限和行为边界，`conventions.md` 只扩展、具象化根 `AGENTS.md`。反复出现的项目坑应补充到 `conventions.md`。
 
-Agent definition 是纯数据，没有 runtime disposer。单文件 HMR 只替换 Agent Slot，旧 turn lease 继续使用旧 instructions。
+`workflows/` 与 `knowledge/` 进入 Agent 指令；`tools/<name>/index.ts` 是由 `@zhin.js/tool` 校验、审批和审计的私有 Tool；`skills/<name>/SKILL.md` 是由 `@zhin.js/skill` 投影的私有 Skill。目录结构只声明归属，不绕过 Feature 准入。
 
-## 依赖
+## Projection 与热重载
 
-只依赖 Next Kernel 与 Feature Kit，不引入 AI SDK、模型 provider、Markdown/YAML parser 或数据库。
+`AgentIndex.list()` 返回全树 qualified descriptors；`visible(owner)` 和 `get(owner, name)` 使用 nearest-owner inheritance。Agent 的 manifest、入口文件及资源文件变化只替换对应 Slot，进行中的 turn 继续使用原 generation。
 
 ## 验证
 

package/lib/definition.d.ts

@@ -1,15 +1,49 @@
 import type { ValidationContext } from '@zhin.js/feature-kit';
 declare const agentBrand: "zhin.agent/1";
+export type AgentScope = 'private' | 'group' | 'channel';
+export interface AgentTriggerRules {
+    readonly filePatterns: readonly string[];
+    readonly keywords: readonly string[];
+}
+export interface AgentResource {
+    readonly path: string;
+    readonly content: string;
+}
+export interface AgentPackageSource {
+    readonly manifest: unknown;
+    readonly files: Readonly<Record<string, string>>;
+    readonly workflows: readonly AgentResource[];
+    readonly knowledge: readonly AgentResource[];
+    readonly privateToolNames?: readonly string[];
+    readonly privateSkillNames?: readonly string[];
+}
 export interface AgentDefinition {
     readonly $feature: typeof agentBrand;
+    /** Stable capability id derived from agents/<name>/. */
     readonly name: string;
+    /** Human-readable name declared by agent.json. */
+    readonly displayName: string;
+    readonly version: string;
     readonly description: string;
+    readonly triggerRules: AgentTriggerRules;
+    readonly entryPoints: readonly string[];
     readonly instructions: string;
+    readonly workflows: readonly AgentResource[];
+    readonly knowledge: readonly AgentResource[];
+    readonly toolNames?: readonly string[];
+    readonly skillNames?: readonly string[];
+    readonly disallowedTools?: readonly string[];
+    readonly tags?: readonly string[];
+    readonly role?: string;
+    readonly contextMode?: 'fork' | 'fresh';
+    readonly maxIterations?: number;
+    readonly model?: string;
+    readonly provider?: string;
+    readonly effort?: 'low' | 'medium' | 'high' | 'max';
+    readonly memory?: 'user' | 'session' | 'agent';
+    readonly platforms?: readonly string[];
+    readonly scopes?: readonly AgentScope[];
+    readonly permissions?: readonly string[];
 }
-declare module '@zhin.js/plugin-runtime' {
-    interface PluginSetupContext<TConfig = unknown> {
-        addAgent(localName: string, markdown: string): void;
-    }
-}
-export declare function parseAgentMarkdown(value: unknown, context: ValidationContext): AgentDefinition;
+export declare function parseAgentPackage(value: unknown, context: ValidationContext): AgentDefinition;
 export {};

package/lib/definition.js

@@ -1,18 +1,157 @@
 const agentBrand = 'zhin.agent/1';
-export function parseAgentMarkdown(value, context) {
-    if (typeof value !== 'string' || !value.trim()) {
-        throw new TypeError(`Agent ${context.source} must contain Markdown instructions`);
+const AGENT_NAME = /^[a-z0-9][a-z0-9-]*$/u;
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+const ENTRY_POINT = /^[a-z0-9][a-z0-9._-]*\.md$/u;
+const REQUIRED_ENTRY_POINTS = ['system.md', 'boundaries.md', 'conventions.md'];
+export function parseAgentPackage(value, context) {
+    if (!isRecord(value))
+        throw new TypeError(`Agent ${context.source} must be a package source`);
+    const source = value;
+    const manifest = parseManifest(source.manifest, context);
+    if (!AGENT_NAME.test(context.localName)) {
+        throw new TypeError(`Agent directory ${context.localName} must use lowercase kebab-case`);
+    }
+    const files = isRecord(source.files) ? source.files : {};
+    const entryPoints = stringList(manifest.entry_points, 'entry_points', true);
+    for (const required of REQUIRED_ENTRY_POINTS) {
+        if (!entryPoints.includes(required)) {
+            throw new TypeError(`Agent ${context.source} entry_points must include ${required}`);
+        }
     }
+    for (const entry of entryPoints) {
+        if (!ENTRY_POINT.test(entry)) {
+            throw new TypeError(`Agent ${context.source} entry point must be a root Markdown file: ${entry}`);
+        }
+        if (typeof files[entry] !== 'string' || !files[entry].trim()) {
+            throw new TypeError(`Agent ${context.source} entry point is missing or empty: ${entry}`);
+        }
+    }
+    const workflows = resources(source.workflows, 'workflows');
+    const knowledge = resources(source.knowledge, 'knowledge');
     return Object.freeze({
         $feature: agentBrand,
         name: context.localName,
-        description: markdownSummary(value, context.localName),
-        instructions: value,
+        displayName: nonEmptyText(manifest.name, 'name'),
+        version: semanticVersion(manifest.version),
+        description: nonEmptyText(manifest.description, 'description'),
+        triggerRules: Object.freeze({
+            filePatterns: stringList(manifest.trigger_rules.file_patterns ?? [], 'trigger_rules.file_patterns'),
+            keywords: stringList(manifest.trigger_rules.keywords ?? [], 'trigger_rules.keywords'),
+        }),
+        entryPoints,
+        instructions: assembleInstructions(entryPoints, files, workflows, knowledge),
+        workflows,
+        knowledge,
+        toolNames: combinedNames(manifest.tools, source.privateToolNames, 'tools'),
+        skillNames: combinedNames(manifest.skills, source.privateSkillNames, 'skills'),
+        disallowedTools: optionalStringList(manifest.disallowed_tools, 'disallowed_tools'),
+        tags: optionalStringList(manifest.tags, 'tags'),
+        role: optionalText(manifest.role, 'role'),
+        contextMode: optionalEnum(manifest.context_mode, 'context_mode', ['fork', 'fresh']),
+        maxIterations: optionalPositiveInteger(manifest.max_iterations, 'max_iterations'),
+        model: optionalText(manifest.model, 'model'),
+        provider: optionalText(manifest.provider, 'provider'),
+        effort: optionalEnum(manifest.effort, 'effort', ['low', 'medium', 'high', 'max']),
+        memory: optionalEnum(manifest.memory, 'memory', ['user', 'session', 'agent']),
+        platforms: optionalStringList(manifest.platforms, 'platforms'),
+        scopes: optionalScopes(manifest.scopes),
+        permissions: optionalStringList(manifest.permissions, 'permissions'),
     });
 }
-function markdownSummary(markdown, fallback) {
-    const line = markdown.split(/\r?\n/u)
-        .map((value) => value.trim())
-        .find((value) => /^#+\s+\S/u.test(value));
-    return line?.replace(/^#+\s*/u, '') ?? fallback;
+function assembleInstructions(entryPoints, files, workflows, knowledge) {
+    const sections = entryPoints.map((entry) => `## ${entry}\n\n${String(files[entry]).trim()}`);
+    for (const resource of [...workflows, ...knowledge]) {
+        sections.push(`## ${resource.path}\n\n${resource.content.trim()}`);
+    }
+    return sections.join('\n\n');
+}
+function parseManifest(value, context) {
+    if (!isRecord(value))
+        throw new TypeError(`Agent ${context.source} agent.json must contain an object`);
+    const allowed = new Set([
+        'name', 'version', 'description', 'trigger_rules', 'entry_points', 'tools', 'skills',
+        'disallowed_tools', 'tags', 'role', 'context_mode', 'max_iterations', 'model',
+        'provider', 'effort', 'memory', 'platforms', 'scopes', 'permissions',
+    ]);
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length)
+        throw new TypeError(`Agent ${context.source} agent.json has unknown fields: ${unknown.join(', ')}`);
+    if (!isRecord(value.trigger_rules)) {
+        throw new TypeError(`Agent ${context.source} trigger_rules must be an object`);
+    }
+    const triggerUnknown = Object.keys(value.trigger_rules)
+        .filter((key) => key !== 'file_patterns' && key !== 'keywords');
+    if (triggerUnknown.length) {
+        throw new TypeError(`Agent ${context.source} trigger_rules has unknown fields: ${triggerUnknown.join(', ')}`);
+    }
+    return value;
+}
+function resources(value, field) {
+    if (!Array.isArray(value))
+        throw new TypeError(`Agent package ${field} must be an array`);
+    return Object.freeze(value.map((item) => {
+        if (!isRecord(item) || typeof item.path !== 'string' || typeof item.content !== 'string') {
+            throw new TypeError(`Agent package ${field} entries must contain path and content strings`);
+        }
+        return Object.freeze({ path: item.path, content: item.content });
+    }));
+}
+function stringList(value, field, required = false) {
+    if (!Array.isArray(value) || (required && value.length === 0)
+        || value.some((entry) => typeof entry !== 'string' || !entry.trim())) {
+        throw new TypeError(`Agent agent.json ${field} must contain non-empty strings`);
+    }
+    const normalized = value.map((entry) => String(entry).trim());
+    if (new Set(normalized).size !== normalized.length) {
+        throw new TypeError(`Agent agent.json ${field} must not contain duplicates`);
+    }
+    return Object.freeze(normalized);
+}
+function optionalStringList(value, field) {
+    return value === undefined ? undefined : stringList(value, field);
+}
+function combinedNames(declared, discovered, field) {
+    const values = [...(optionalStringList(declared, field) ?? []), ...(discovered ?? [])];
+    return values.length ? Object.freeze([...new Set(values)]) : undefined;
+}
+function nonEmptyText(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`Agent agent.json ${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function optionalText(value, field) {
+    return value === undefined ? undefined : nonEmptyText(value, field);
+}
+function semanticVersion(value) {
+    const version = nonEmptyText(value, 'version');
+    if (!VERSION.test(version))
+        throw new TypeError('Agent agent.json version must be semantic version');
+    return version;
+}
+function optionalPositiveInteger(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || Number(value) < 1) {
+        throw new TypeError(`Agent agent.json ${field} must be a positive integer`);
+    }
+    return Number(value);
+}
+function optionalEnum(value, field, allowed) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new TypeError(`Agent agent.json ${field} must be one of: ${allowed.join(', ')}`);
+    }
+    return value;
+}
+function optionalScopes(value) {
+    const scopes = optionalStringList(value, 'scopes');
+    if (scopes?.some((scope) => scope !== 'private' && scope !== 'group' && scope !== 'channel')) {
+        throw new TypeError('Agent agent.json scopes must be private, group, or channel');
+    }
+    return scopes;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/lib/provider.js

@@ -1,36 +1,80 @@
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { featureId } from '@zhin.js/plugin-runtime';
 import { defineFeatureProvider, } from '@zhin.js/feature-kit';
 import { AgentIndex } from './agent-index.js';
-import { parseAgentMarkdown } from './definition.js';
+import { parseAgentPackage } from './definition.js';
 export const agentFeatureId = featureId('zhin.agent');
-const agentFiles = {
-    id: 'agent-markdown',
+const agentPackages = {
+    id: 'agent-package',
     async *discover(context) {
-        const directory = join(context.packageRoot, 'agents');
-        const entries = [...await context.host.list(directory)]
+        const root = join(context.packageRoot, 'agents');
+        const entries = [...await context.host.list(root)]
             .sort((left, right) => left.name.localeCompare(right.name));
         for (const entry of entries) {
-            if (entry.kind !== 'file' || !isAgentFile(entry.name))
+            if (entry.kind !== 'directory' || !isAgentName(entry.name))
                 continue;
+            const directory = join(root, entry.name);
+            const children = await context.host.list(directory);
+            if (!children.some((child) => child.kind === 'file' && child.name === 'agent.json'))
+                continue;
+            const relatedSources = [
+                ...children
+                    .filter((child) => child.kind === 'file' && child.name !== 'agent.json')
+                    .map((child) => join(directory, child.name)),
+                ...await discoverRelatedSources(context.host, directory),
+            ];
             yield {
-                localName: entry.name.slice(0, -'.agent.md'.length),
-                source: join(directory, entry.name),
+                localName: entry.name,
+                source: join(directory, 'agent.json'),
+                relatedSources: Object.freeze(relatedSources),
                 target: 'server',
             };
         }
     },
-    load(source, context) {
-        return context.host.readText(source.source);
+    async load(source, context) {
+        const directory = dirname(source.source);
+        const manifest = JSON.parse(await context.host.readText(source.source));
+        const files = await readRootFiles(context.host, directory);
+        return {
+            manifest,
+            files,
+            workflows: await readResourceDirectory(context.host, directory, 'workflows'),
+            knowledge: await readResourceDirectory(context.host, directory, 'knowledge'),
+            privateToolNames: (await childDirectories(context.host, join(directory, 'tools')))
+                .map((name) => `agent__${source.localName}__${name}`),
+            privateSkillNames: (await childDirectories(context.host, join(directory, 'skills')))
+                .map((name) => `agent__${source.localName}__${name}`),
+        };
     },
 };
+async function discoverRelatedSources(host, directory) {
+    const result = [];
+    for (const name of ['workflows', 'tools', 'skills', 'knowledge']) {
+        await collectFiles(host, join(directory, name), result);
+    }
+    return result;
+}
+async function collectFiles(host, directory, result) {
+    for (const entry of await host.list(directory)) {
+        const target = join(directory, entry.name);
+        if (entry.kind === 'directory' && isAgentName(entry.name))
+            await collectFiles(host, target, result);
+        else if (entry.kind === 'file')
+            result.push(target);
+    }
+}
+async function childDirectories(host, directory) {
+    return [...await host.list(directory)]
+        .filter((entry) => entry.kind === 'directory' && isAgentName(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+}
 const agentFeature = defineFeatureProvider({
     protocol: 1,
     id: agentFeatureId,
     authoring: {
-        setupMethod: 'addAgent',
-        conventions: [agentFiles],
-        validate: parseAgentMarkdown,
+        conventions: [agentPackages],
+        validate: parseAgentPackage,
     },
     runtime: {
         project(slots, context) {
@@ -38,8 +82,28 @@ const agentFeature = defineFeatureProvider({
         },
     },
 });
-function isAgentFile(value) {
-    return /^[a-z0-9][a-z0-9-]*\.agent\.md$/u.test(value);
+async function readRootFiles(host, directory) {
+    const entries = await host.list(directory);
+    const files = await Promise.all(entries
+        .filter((entry) => entry.kind === 'file' && entry.name !== 'agent.json')
+        .map(async (entry) => [entry.name, await host.readText(join(directory, entry.name))]));
+    return Object.freeze(Object.fromEntries(files));
+}
+async function readResourceDirectory(host, agentDirectory, name) {
+    const directory = join(agentDirectory, name);
+    const entries = [...await host.list(directory)]
+        .filter((entry) => entry.kind === 'file' && isResourceFile(entry.name))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    return Promise.all(entries.map(async (entry) => Object.freeze({
+        path: `${name}/${entry.name}`,
+        content: await host.readText(join(directory, entry.name)),
+    })));
+}
+function isAgentName(value) {
+    return /^[a-z0-9][a-z0-9-]*$/u.test(value);
+}
+function isResourceFile(value) {
+    return /^[a-zA-Z0-9][a-zA-Z0-9._-]*\.(?:md|txt|json|ya?ml|csv|sh)$/u.test(value);
 }
 export { agentFeature };
 export default agentFeature;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/agent-feature",
-  "version": "1.0.13",
+  "version": "1.1.1",
   "description": "Convention-based Markdown Agent Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,8 +17,8 @@
     "src"
   ],
   "dependencies": {
-    "@zhin.js/feature-kit": "1.0.13",
-    "@zhin.js/plugin-runtime": "1.1.8"
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/plugin-runtime": "1.1.10"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/definition.ts

@@ -1,37 +1,254 @@
 import type { ValidationContext } from '@zhin.js/feature-kit';
 
 const agentBrand = 'zhin.agent/1' as const;
+const AGENT_NAME = /^[a-z0-9][a-z0-9-]*$/u;
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+const ENTRY_POINT = /^[a-z0-9][a-z0-9._-]*\.md$/u;
+const REQUIRED_ENTRY_POINTS = ['system.md', 'boundaries.md', 'conventions.md'] as const;
+
+export type AgentScope = 'private' | 'group' | 'channel';
+
+export interface AgentTriggerRules {
+  readonly filePatterns: readonly string[];
+  readonly keywords: readonly string[];
+}
+
+export interface AgentResource {
+  readonly path: string;
+  readonly content: string;
+}
+
+export interface AgentPackageSource {
+  readonly manifest: unknown;
+  readonly files: Readonly<Record<string, string>>;
+  readonly workflows: readonly AgentResource[];
+  readonly knowledge: readonly AgentResource[];
+  readonly privateToolNames?: readonly string[];
+  readonly privateSkillNames?: readonly string[];
+}
 
 export interface AgentDefinition {
   readonly $feature: typeof agentBrand;
+  /** Stable capability id derived from agents/<name>/. */
   readonly name: string;
+  /** Human-readable name declared by agent.json. */
+  readonly displayName: string;
+  readonly version: string;
   readonly description: string;
+  readonly triggerRules: AgentTriggerRules;
+  readonly entryPoints: readonly string[];
   readonly instructions: string;
+  readonly workflows: readonly AgentResource[];
+  readonly knowledge: readonly AgentResource[];
+  readonly toolNames?: readonly string[];
+  readonly skillNames?: readonly string[];
+  readonly disallowedTools?: readonly string[];
+  readonly tags?: readonly string[];
+  readonly role?: string;
+  readonly contextMode?: 'fork' | 'fresh';
+  readonly maxIterations?: number;
+  readonly model?: string;
+  readonly provider?: string;
+  readonly effort?: 'low' | 'medium' | 'high' | 'max';
+  readonly memory?: 'user' | 'session' | 'agent';
+  readonly platforms?: readonly string[];
+  readonly scopes?: readonly AgentScope[];
+  readonly permissions?: readonly string[];
 }
 
-declare module '@zhin.js/plugin-runtime' {
-  // Type parameter name must match the base PluginSetupContext declaration (TS2428).
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  interface PluginSetupContext<TConfig = unknown> {
-    addAgent(localName: string, markdown: string): void;
-  }
+interface AgentManifest {
+  readonly name: string;
+  readonly version: string;
+  readonly description: string;
+  readonly trigger_rules: {
+    readonly file_patterns?: readonly string[];
+    readonly keywords?: readonly string[];
+  };
+  readonly entry_points: readonly string[];
+  readonly tools?: readonly string[];
+  readonly skills?: readonly string[];
+  readonly disallowed_tools?: readonly string[];
+  readonly tags?: readonly string[];
+  readonly role?: string;
+  readonly context_mode?: 'fork' | 'fresh';
+  readonly max_iterations?: number;
+  readonly model?: string;
+  readonly provider?: string;
+  readonly effort?: 'low' | 'medium' | 'high' | 'max';
+  readonly memory?: 'user' | 'session' | 'agent';
+  readonly platforms?: readonly string[];
+  readonly scopes?: readonly AgentScope[];
+  readonly permissions?: readonly string[];
 }
 
-export function parseAgentMarkdown(value: unknown, context: ValidationContext): AgentDefinition {
-  if (typeof value !== 'string' || !value.trim()) {
-    throw new TypeError(`Agent ${context.source} must contain Markdown instructions`);
+export function parseAgentPackage(value: unknown, context: ValidationContext): AgentDefinition {
+  if (!isRecord(value)) throw new TypeError(`Agent ${context.source} must be a package source`);
+  const source = value as unknown as AgentPackageSource;
+  const manifest = parseManifest(source.manifest, context);
+  if (!AGENT_NAME.test(context.localName)) {
+    throw new TypeError(`Agent directory ${context.localName} must use lowercase kebab-case`);
+  }
+  const files = isRecord(source.files) ? source.files : {};
+  const entryPoints = stringList(manifest.entry_points, 'entry_points', true);
+  for (const required of REQUIRED_ENTRY_POINTS) {
+    if (!entryPoints.includes(required)) {
+      throw new TypeError(`Agent ${context.source} entry_points must include ${required}`);
+    }
   }
+  for (const entry of entryPoints) {
+    if (!ENTRY_POINT.test(entry)) {
+      throw new TypeError(`Agent ${context.source} entry point must be a root Markdown file: ${entry}`);
+    }
+    if (typeof files[entry] !== 'string' || !files[entry].trim()) {
+      throw new TypeError(`Agent ${context.source} entry point is missing or empty: ${entry}`);
+    }
+  }
+  const workflows = resources(source.workflows, 'workflows');
+  const knowledge = resources(source.knowledge, 'knowledge');
   return Object.freeze({
     $feature: agentBrand,
     name: context.localName,
-    description: markdownSummary(value, context.localName),
-    instructions: value,
+    displayName: nonEmptyText(manifest.name, 'name'),
+    version: semanticVersion(manifest.version),
+    description: nonEmptyText(manifest.description, 'description'),
+    triggerRules: Object.freeze({
+      filePatterns: stringList(manifest.trigger_rules.file_patterns ?? [], 'trigger_rules.file_patterns'),
+      keywords: stringList(manifest.trigger_rules.keywords ?? [], 'trigger_rules.keywords'),
+    }),
+    entryPoints,
+    instructions: assembleInstructions(entryPoints, files, workflows, knowledge),
+    workflows,
+    knowledge,
+    toolNames: combinedNames(manifest.tools, source.privateToolNames, 'tools'),
+    skillNames: combinedNames(manifest.skills, source.privateSkillNames, 'skills'),
+    disallowedTools: optionalStringList(manifest.disallowed_tools, 'disallowed_tools'),
+    tags: optionalStringList(manifest.tags, 'tags'),
+    role: optionalText(manifest.role, 'role'),
+    contextMode: optionalEnum(manifest.context_mode, 'context_mode', ['fork', 'fresh']),
+    maxIterations: optionalPositiveInteger(manifest.max_iterations, 'max_iterations'),
+    model: optionalText(manifest.model, 'model'),
+    provider: optionalText(manifest.provider, 'provider'),
+    effort: optionalEnum(manifest.effort, 'effort', ['low', 'medium', 'high', 'max']),
+    memory: optionalEnum(manifest.memory, 'memory', ['user', 'session', 'agent']),
+    platforms: optionalStringList(manifest.platforms, 'platforms'),
+    scopes: optionalScopes(manifest.scopes),
+    permissions: optionalStringList(manifest.permissions, 'permissions'),
   });
 }
 
-function markdownSummary(markdown: string, fallback: string): string {
-  const line = markdown.split(/\r?\n/u)
-    .map((value) => value.trim())
-    .find((value) => /^#+\s+\S/u.test(value));
-  return line?.replace(/^#+\s*/u, '') ?? fallback;
+function assembleInstructions(
+  entryPoints: readonly string[],
+  files: Readonly<Record<string, unknown>>,
+  workflows: readonly AgentResource[],
+  knowledge: readonly AgentResource[],
+): string {
+  const sections = entryPoints.map((entry) => `## ${entry}\n\n${String(files[entry]).trim()}`);
+  for (const resource of [...workflows, ...knowledge]) {
+    sections.push(`## ${resource.path}\n\n${resource.content.trim()}`);
+  }
+  return sections.join('\n\n');
+}
+
+function parseManifest(value: unknown, context: ValidationContext): AgentManifest {
+  if (!isRecord(value)) throw new TypeError(`Agent ${context.source} agent.json must contain an object`);
+  const allowed = new Set([
+    'name', 'version', 'description', 'trigger_rules', 'entry_points', 'tools', 'skills',
+    'disallowed_tools', 'tags', 'role', 'context_mode', 'max_iterations', 'model',
+    'provider', 'effort', 'memory', 'platforms', 'scopes', 'permissions',
+  ]);
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknown.length) throw new TypeError(`Agent ${context.source} agent.json has unknown fields: ${unknown.join(', ')}`);
+  if (!isRecord(value.trigger_rules)) {
+    throw new TypeError(`Agent ${context.source} trigger_rules must be an object`);
+  }
+  const triggerUnknown = Object.keys(value.trigger_rules)
+    .filter((key) => key !== 'file_patterns' && key !== 'keywords');
+  if (triggerUnknown.length) {
+    throw new TypeError(`Agent ${context.source} trigger_rules has unknown fields: ${triggerUnknown.join(', ')}`);
+  }
+  return value as unknown as AgentManifest;
+}
+
+function resources(value: unknown, field: string): readonly AgentResource[] {
+  if (!Array.isArray(value)) throw new TypeError(`Agent package ${field} must be an array`);
+  return Object.freeze(value.map((item) => {
+    if (!isRecord(item) || typeof item.path !== 'string' || typeof item.content !== 'string') {
+      throw new TypeError(`Agent package ${field} entries must contain path and content strings`);
+    }
+    return Object.freeze({ path: item.path, content: item.content });
+  }));
+}
+
+function stringList(value: unknown, field: string, required = false): readonly string[] {
+  if (!Array.isArray(value) || (required && value.length === 0)
+    || value.some((entry) => typeof entry !== 'string' || !entry.trim())) {
+    throw new TypeError(`Agent agent.json ${field} must contain non-empty strings`);
+  }
+  const normalized = value.map((entry) => String(entry).trim());
+  if (new Set(normalized).size !== normalized.length) {
+    throw new TypeError(`Agent agent.json ${field} must not contain duplicates`);
+  }
+  return Object.freeze(normalized);
+}
+
+function optionalStringList(value: unknown, field: string): readonly string[] | undefined {
+  return value === undefined ? undefined : stringList(value, field);
+}
+
+function combinedNames(
+  declared: unknown,
+  discovered: readonly string[] | undefined,
+  field: string,
+): readonly string[] | undefined {
+  const values = [...(optionalStringList(declared, field) ?? []), ...(discovered ?? [])];
+  return values.length ? Object.freeze([...new Set(values)]) : undefined;
+}
+
+function nonEmptyText(value: unknown, field: string): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new TypeError(`Agent agent.json ${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalText(value: unknown, field: string): string | undefined {
+  return value === undefined ? undefined : nonEmptyText(value, field);
+}
+
+function semanticVersion(value: unknown): string {
+  const version = nonEmptyText(value, 'version');
+  if (!VERSION.test(version)) throw new TypeError('Agent agent.json version must be semantic version');
+  return version;
+}
+
+function optionalPositiveInteger(value: unknown, field: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isInteger(value) || Number(value) < 1) {
+    throw new TypeError(`Agent agent.json ${field} must be a positive integer`);
+  }
+  return Number(value);
+}
+
+function optionalEnum<T extends string>(
+  value: unknown,
+  field: string,
+  allowed: readonly T[],
+): T | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || !allowed.includes(value as T)) {
+    throw new TypeError(`Agent agent.json ${field} must be one of: ${allowed.join(', ')}`);
+  }
+  return value as T;
+}
+
+function optionalScopes(value: unknown): readonly AgentScope[] | undefined {
+  const scopes = optionalStringList(value, 'scopes');
+  if (scopes?.some((scope) => scope !== 'private' && scope !== 'group' && scope !== 'channel')) {
+    throw new TypeError('Agent agent.json scopes must be private, group, or channel');
+  }
+  return scopes as readonly AgentScope[] | undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/src/provider.ts

@@ -1,41 +1,86 @@
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { featureId } from '@zhin.js/plugin-runtime';
 import {
   defineFeatureProvider,
+  type DiscoveryHost,
   type SourceConvention,
 } from '@zhin.js/feature-kit';
 import { AgentIndex } from './agent-index.js';
-import { parseAgentMarkdown } from './definition.js';
+import { parseAgentPackage, type AgentResource } from './definition.js';
 
 export const agentFeatureId = featureId('zhin.agent');
 
-const agentFiles: SourceConvention = {
-  id: 'agent-markdown',
+const agentPackages: SourceConvention = {
+  id: 'agent-package',
   async *discover(context) {
-    const directory = join(context.packageRoot, 'agents');
-    const entries = [...await context.host.list(directory)]
+    const root = join(context.packageRoot, 'agents');
+    const entries = [...await context.host.list(root)]
       .sort((left, right) => left.name.localeCompare(right.name));
     for (const entry of entries) {
-      if (entry.kind !== 'file' || !isAgentFile(entry.name)) continue;
+      if (entry.kind !== 'directory' || !isAgentName(entry.name)) continue;
+      const directory = join(root, entry.name);
+      const children = await context.host.list(directory);
+      if (!children.some((child) => child.kind === 'file' && child.name === 'agent.json')) continue;
+      const relatedSources = [
+        ...children
+          .filter((child) => child.kind === 'file' && child.name !== 'agent.json')
+          .map((child) => join(directory, child.name)),
+        ...await discoverRelatedSources(context.host, directory),
+      ];
       yield {
-        localName: entry.name.slice(0, -'.agent.md'.length),
-        source: join(directory, entry.name),
+        localName: entry.name,
+        source: join(directory, 'agent.json'),
+        relatedSources: Object.freeze(relatedSources),
         target: 'server',
       };
     }
   },
-  load(source, context) {
-    return context.host.readText(source.source);
+  async load(source, context) {
+    const directory = dirname(source.source);
+    const manifest = JSON.parse(await context.host.readText(source.source)) as unknown;
+    const files = await readRootFiles(context.host, directory);
+    return {
+      manifest,
+      files,
+      workflows: await readResourceDirectory(context.host, directory, 'workflows'),
+      knowledge: await readResourceDirectory(context.host, directory, 'knowledge'),
+      privateToolNames: (await childDirectories(context.host, join(directory, 'tools')))
+        .map((name) => `agent__${source.localName}__${name}`),
+      privateSkillNames: (await childDirectories(context.host, join(directory, 'skills')))
+        .map((name) => `agent__${source.localName}__${name}`),
+    };
   },
 };
 
+async function discoverRelatedSources(host: DiscoveryHost, directory: string): Promise<string[]> {
+  const result: string[] = [];
+  for (const name of ['workflows', 'tools', 'skills', 'knowledge'] as const) {
+    await collectFiles(host, join(directory, name), result);
+  }
+  return result;
+}
+
+async function collectFiles(host: DiscoveryHost, directory: string, result: string[]): Promise<void> {
+  for (const entry of await host.list(directory)) {
+    const target = join(directory, entry.name);
+    if (entry.kind === 'directory' && isAgentName(entry.name)) await collectFiles(host, target, result);
+    else if (entry.kind === 'file') result.push(target);
+  }
+}
+
+async function childDirectories(host: DiscoveryHost, directory: string): Promise<string[]> {
+  return [...await host.list(directory)]
+    .filter((entry) => entry.kind === 'directory' && isAgentName(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+}
+
 const agentFeature = defineFeatureProvider({
   protocol: 1,
   id: agentFeatureId,
   authoring: {
-    setupMethod: 'addAgent',
-    conventions: [agentFiles],
-    validate: parseAgentMarkdown,
+    conventions: [agentPackages],
+    validate: parseAgentPackage,
   },
   runtime: {
     project(slots, context) {
@@ -44,8 +89,35 @@ const agentFeature = defineFeatureProvider({
   },
 });
 
-function isAgentFile(value: string): boolean {
-  return /^[a-z0-9][a-z0-9-]*\.agent\.md$/u.test(value);
+async function readRootFiles(host: DiscoveryHost, directory: string): Promise<Readonly<Record<string, string>>> {
+  const entries = await host.list(directory);
+  const files = await Promise.all(entries
+    .filter((entry) => entry.kind === 'file' && entry.name !== 'agent.json')
+    .map(async (entry) => [entry.name, await host.readText(join(directory, entry.name))] as const));
+  return Object.freeze(Object.fromEntries(files));
+}
+
+async function readResourceDirectory(
+  host: DiscoveryHost,
+  agentDirectory: string,
+  name: 'workflows' | 'knowledge',
+): Promise<readonly AgentResource[]> {
+  const directory = join(agentDirectory, name);
+  const entries = [...await host.list(directory)]
+    .filter((entry) => entry.kind === 'file' && isResourceFile(entry.name))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  return Promise.all(entries.map(async (entry) => Object.freeze({
+    path: `${name}/${entry.name}`,
+    content: await host.readText(join(directory, entry.name)),
+  })));
+}
+
+function isAgentName(value: string): boolean {
+  return /^[a-z0-9][a-z0-9-]*$/u.test(value);
+}
+
+function isResourceFile(value: string): boolean {
+  return /^[a-zA-Z0-9][a-zA-Z0-9._-]*\.(?:md|txt|json|ya?ml|csv|sh)$/u.test(value);
 }
 
 export { agentFeature };