@capybearista/opencode-agents-loader 1.0.0 → 2.0.1

package/README.md

@@ -1,32 +1,103 @@
-# @capybearista/opencode-agents-loader
+# opencode-agents-loader
 
-An [OpenCode](https://opencode.ai) plugin that extends command and agent discovery to `~/.agents/` and `.agents/` directories.
+<p align="center">Extend V2 agent and command discovery to the .agents/ directory standard</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@capybearista/opencode-agents-loader"><img alt="npm version" src="https://img.shields.io/npm/v/@capybearista/opencode-agents-loader?style=flat-square&color=8d60e6" /></a>
+  <a href="https://www.npmjs.com/package/@capybearista/opencode-agents-loader"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@capybearista/opencode-agents-loader?style=flat-square&color=6067e6" /></a>
+  <a href="https://opencode.ai"><img alt="opencode" src="https://img.shields.io/badge/OpenCode-Plugin-orange?style=flat-square&color=60a5e6" /></a>
+  <a href="https://opensource.org/licenses/MPL-2.0"><img alt="license" src="https://img.shields.io/badge/License-MPL--2.0-blue.svg?style=flat-square&color=60dfe6" /></a>
+</p>
+
+---
 
 ## Why?
 
-While OpenCode natively uses `.opencode/` for its configuration, the `.agents/` directory is becoming an open standard for agent-based tools. This plugin's primary intention is to support this convention, enabling better interoperability between OpenCode and other harnesses, especially if...
-- you want to commit project-specific agent capabilities for other contributors to make use of
-- you yourself use other harnesses (that aren't named "Claude Code", though you could symlink `.agents/<commands|agents>/` and `.claude/<commands|agents>/`)
+> The `.agents/` directory is becoming an open standard for agent-based tools. This plugin lets OpenCode read **commands** and **agents** from `~/.agents/` and `.agents/` directories, enabling interoperability with other harnesses and cleaner project organization.
+
+## Philosophy: Extending OpenCode
+
+OpenCode is designed to be highly extensible. This plugin expands the "Agents" standard.
+
+### Architecture
+
+```text
+src/index.ts
+    └── starts the command and agent bridges
+
+command-bridge.ts
+    ├── links .agents/ command and agent files into native .opencode/ directories
+    ├── records link ownership in manifests and locks
+    └── watches the sources for changes
+
+agent-source.ts
+    └── validates agent frontmatter before an agent link is created
+```
+
+OpenCode natively reads from `.opencode/` and configuration files. This plugin links `.agents/`
+command and agent files into the matching native directories with managed relative symlinks, so
+OpenCode discovers and runs them as if they lived in `.opencode/`. It only extends discovery:
+source files are never copied or rewritten, and native files and explicit config entries always
+win.
+
+## Features
 
-It is also useful if you want to keep your OpenCode config separate from your custom commands and agents, or if you want to share agents across multiple projects via a global `~/.agents/` directory.
+- **Discovery**: finds command and agent markdown files in `~/.agents/` and `.agents/` directories.
+- **Managed symlinks**: materializes relative symlinks so native OpenCode owns parsing and execution.
+- **Native precedence**: respects existing native files and explicit config entries — plugin entries never overwrite native config.
+- **Automatic startup**: starts both native bridges automatically; no manual sync step is required.
+- **Byte preservation**: preserves complete command and agent source bytes and nested relative names by symlink, including shell and subagent templates.
+- **Global destination**: uses `OPENCODE_CONFIG_DIR` for the global native destination; global sources remain in `~/.agents/`.
 
-## Installation
+## Install
 
-Add the plugin to your `opencode.json`:
+### OpenCode V2
+
+Add it under the `"plugins"` key in `opencode.json(c)`:
+
+```json
+{
+  "plugins": ["@capybearista/opencode-agents-loader@latest"]
+}
+```
+
+Server entry only, so `cli.json` needs no entry.
+
+### OpenCode V1
+
+Add it under the `"plugin"` key in `opencode.json(c)`:
 
 ```json
 {
-  "plugin": ["@capybearista/opencode-agents-loader"]
+  "plugin": ["@capybearista/opencode-agents-loader@1.0.0"]
 }
 ```
 
-## Directory Layout
+Server entry only, so `tui.json(c)` needs no entry.
+
+See the [V1 plugin guide](../../docs/v1-plugins.md) for details.
+
+### Uninstall
+
+Remove the plugin from `"plugin(s)"` from the respective config files they were added to. 
+
+## Usage
+
+Create markdown files with YAML frontmatter:
+
+```md
+---
+description: "Does something useful"
+---
+
+# Command Body
+This is the command content that the agent will process.
+```
 
 ### Commands
 
 Place command markdown files in `command/` or `commands/` subdirectories:
 
-```
+```text
 ~/.agents/
   commands/
     hello.md
@@ -42,7 +113,7 @@ Place command markdown files in `command/` or `commands/` subdirectories:
 
 Place agent markdown files in `agent/` or `agents/` subdirectories:
 
-```
+```text
 ~/.agents/
   agents/
     reviewer.md
@@ -53,28 +124,81 @@ Place agent markdown files in `agent/` or `agents/` subdirectories:
     project-expert.md
 ```
 
-## File Format
+Only `agent/` and `agents/` are plugin source directories. `mode/` and `modes/` remain native
+OpenCode aliases and are not treated as new plugin agent sources; a native mode with the same name
+still reserves that name. A source agent's declared `mode` is preserved, including `subagent`; the
+bridge never infers or forces `primary`.
+
+### How it works
+
+Setup links `.agents/` files into the matching native `.opencode/` directories with managed
+relative symlinks: each project scope maps into its own scope, and global `~/.agents/` maps into
+the global native root. Native OpenCode owns parsing, precedence, and execution; source files are
+never copied or rewritten, and destination directories must support symlink creation (there is no
+copy fallback). Native files and explicit config entries always win over bridged links; where
+singular and plural source spellings both exist, the plural (`commands/`, `agents/`) wins, and
+nested names stay nested. Sources with invalid metadata are skipped with a diagnostic rather than
+linked. Links reconcile automatically as sources change; if an update does not appear, restart
+OpenCode. Command execution itself is not emulated — `$ARGUMENTS`, shell blocks, and `subagent`
+behavior stay native. See [Development Notes](#development-notes) for the bridge internals.
+
+## Configuration
+
+There are no plugin-specific settings. After registering the plugin in the V2 server profile, it
+reads the documented `.agents/` directories automatically. Keep the V2 profile separate from any
+V1 configuration as described in [Install](#install).
+
+## Troubleshooting
+
+- If commands or agents don't appear, verify your files end in `.md` and include valid YAML frontmatter
+- Confirm the directory naming is `commands/` or `command/`, `agents/` or `agent/`
+- Inspect the scoped `.agents-loader/{commands,agents}-manifest.json` and diagnostics before removing
+  anything; unowned native files are intentionally preserved
+- If synchronization stops after a crash, inspect `.agents-loader/agents.lock` and
+  `.agents-loader/commands.lock`. The bridge deliberately fails closed on held locks,
+  including abandoned ones. Stop **all** OpenCode processes using that config directory
+  before moving lock files aside for recovery; never remove a lock while a process might
+  be reconciling. Preserve the manifests, then restart OpenCode.
+- An active plugin does not guarantee every scope reconciled. Unsafe scopes emit
+  diagnostic errors; when safe reconciliation resumes, the bridge reports that pending
+  cleanup may remain. This message does not mean all stale links have been removed.
+
+## Development Notes
+
+### Bridge internals
+
+Each destination parent keeps version-1 ownership metadata under `.agents-loader/`
+(`commands-manifest.json` + `commands.lock` for commands, `agents-manifest.json` + `agents.lock`
+for agents; project-local under `.opencode/.agents-loader/`, global under
+`$OPENCODE_CONFIG_DIR/.agents-loader/`). Only exact recorded symlinks are ever removed; anything
+else fails closed with a diagnostic. Writes are atomic behind a bounded per-domain lock — never
+delete a stale lock while OpenCode instances are running.
+
+Each bridge polls every 500 ms for source edits, creations, deletions, renames, and
+native-name reservation changes, emitting a reload signal once per observed change. A reload
+signal is not a native rescan: changes may need an OpenCode rescan or a restart, and no
+universal hot-reload guarantee is made.
 
-Both commands and agents use markdown files with YAML frontmatter. Find the specifics at the official OpenCode docs:
-- Commands: https://opencode.ai/docs/commands/#markdown
-- Agents: https://opencode.ai/docs/agents/#markdown
 
-## Precedence
+The package checks include the real local-directory resolver regression, build/static checks, and
+the scoped bridge tests. In one isolated OpenCode setup, human verification confirmed agent and
+command discovery and native execution, global/project precedence fixtures, live additions,
+restart-required description changes, and removal cleanup. These observations do not promise
+identical watcher behavior for every OpenCode version, platform, provider, or config layout.
 
-Existing config entries from `.opencode/` directories always take precedence over `.agents/` entries. The plugin only injects entries that **do not already exist**.
+## Contributing
 
-Within `.agents/` directories, the closest directory to your project wins. The precedence order (highest to lowest):
+This package lives in the `opencode-plugins` monorepo.
 
-1. `.opencode/` directory (project-local)
-2. `.agents/` directory (closest to project root)
-3. `.agents/` parent directories (walking up the tree)
-4. `~/.config/opencode/` directory (global)
-5. `~/.agents/` directory (global)
+See the [contribution guidelines](../../CONTRIBUTING.md) before opening a pull request.
 
-## Requirements
+- From the monorepo root, run `bun run build` before artifact checks, then `bun run typecheck`,`bun run lint`, and the canonical `bun run test` Turbo pipeline. Do not use bare root `bun test` as the workspace check.
+- For a focused run, `bun test` is supported from this package directory; its tests include the real local-directory resolver regression.
+- `bun run check` writes Biome changes; use it only when formatting changes are intended.
+- Prefer small, direct changes.
 
-- OpenCode >= 1.14.25
+Please open an issue or check for existing ones before creating a pull request.
 
 ## License
 
-MPL-2.0
+[MPL-2.0](./LICENSE.txt)

package/dist/agent-source.d.ts

@@ -0,0 +1,28 @@
+import type { Agent as AgentSchema } from "@opencode/plugin";
+export interface MarkdownEntry {
+    readonly data: Record<string, unknown>;
+    readonly content: string;
+}
+type AgentModel = NonNullable<AgentSchema.Info["model"]>;
+type AgentPermission = AgentSchema.Info["permissions"][number];
+export interface AgentPatch {
+    readonly system: string;
+    readonly model?: AgentModel;
+    readonly request?: {
+        readonly headers?: Record<string, string>;
+        readonly body?: Record<string, unknown>;
+    };
+    readonly description?: string;
+    readonly mode?: AgentSchema.Info["mode"];
+    readonly hidden?: boolean;
+    readonly color?: NonNullable<AgentSchema.Info["color"]>;
+    readonly steps?: NonNullable<AgentSchema.Info["steps"]>;
+    readonly disabled?: boolean;
+    readonly permissions: AgentPermission[];
+}
+export declare function fallbackSanitization(content: string): string;
+export declare function parseMarkdown(filePath: string): Promise<MarkdownEntry>;
+export declare function parseMarkdownContent(template: string, source: string): MarkdownEntry;
+export declare function validateAgentContent(source: string, content: Buffer, home?: string): string | undefined;
+export declare function convertAgent(_name: string, entry: MarkdownEntry, home?: string): AgentPatch | undefined;
+export {};