@jianxx/dsh-cc-plugin-loader 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/compat/cc-plugin-loader/README.md
+README.md: 351640f50f5087cee64f9ed9d1fe4801bd65f634
+README.zh.md: c9c105c663418ba580c05138e65c1ea7dc37e938

package/README.md

@@ -0,0 +1,45 @@
+# @jianxx/dsh-cc-plugin-loader
+
+English | [中文](README.zh.md)
+
+Load a Claude Code plugin's `plugin.json` manifest and mount each component as an in-memory dsh plugin.
+
+This compatibility loader reads a CC plugin manifest subset, translates each component with the pure helpers from [`@jianxx/dsh-cc-skill-loader`](../../skill/skill-claude-code/README.md) and [`@jianxx/dsh-cc-claude-code-agents`](../../preset/claude-code-agents/README.md), and consults the host seam for that component through `ctx.get(...)`. It is not a runtime: it produces typed mounts and a structural report, leaving execution to the seams it registers onto.
+
+## Loader
+
+`mountCcPlugin(ctx, { root, seams? })` reads `${root}/plugin.json`, validates the manifest subset, and mounts every present component as a Cordis effect. It returns `{ report, dispose }` — `report` is the per-component outcome, and `dispose` recalls every mounted component (a context teardown calls it automatically).
+
+### Manifest subset
+
+The loader validates `name` (mandatory, kebab-case), `version`, `description`, `author`, and the component fields `commands`, `agents`, `skills`, `hooks`, `mcpServers`, and `settings`. A malformed manifest throws at load with the plugin name. Unknown top-level fields are ignored, matching Claude Code's tolerant handling.
+
+### Components and their seams
+
+Each component is peer-style: the loader probes the host seam via `ctx.get(...)` and reports the component `skipped` (never failing the whole load) when the seam is absent.
+
+| Component | Source | Seam (probed) | Translation |
+|---|---|---|---|
+| `commands` | manifest inline or source | `commands` | registers each slash command via `register`; the handler returns the command content |
+| `agents` | `agents/` dir or manifest paths | `subagents` | loads `AgentDefinition`s via `loadAgentsDir` and registers each as a named provider via `registerProvider` |
+| `skills` | `skills/` dir or manifest paths | `skills` | discovers `SKILL.md` via `discoverCcSkills`, parses frontmatter, and registers each as a runtime skill via `register` |
+| `hooks` | `hooks/hooks.json` or inline | `hooks` (guest) | injects the per-event hook map via `mergePluginHooks` |
+| `mcpServers` | inline record or `.mcp.json` | `mcp` (guest) | registers each server via `registerServer` (tool naming is the seam's responsibility) |
+| `settings` | manifest record | `settings` (guest) | filters to the allowlist (currently `agent`) and writes via `set` |
+
+The `hooks` and `mcp` seams have no harness-owned service today; a deployment that wants those components provides a guest seam or they are reported skipped.
+
+## Skill semantic wiring
+
+On top of the skill mount, this package is the consumer that turns `skill-claude-code`'s metadata into actionable registrations:
+
+- **`allowed-tools`** — `skillToolRestriction(metadata)` builds the allow-only `tools.restrict()` filter; `applySkillRestriction(metadata, agent)` applies it to a scoped agent and returns the disposer.
+- **`context: fork`** — `resolveSkillExecution(metadata, subagentsPresent)` routes the skill to subagent execution; when the subagent seam is absent it downgrades to inline and is reported.
+- **`paths`** — `registerSkillPathActivator(ctx, skill, projectRoot)` wires the `fs/observed` path activator for conditional activation.
+- **Inline shell** — `activationFor(metadata, subagentsPresent)` reports `forbidInlineShell` (a `shell: false` skill must not open an inline shell).
+
+## Known Limitations and Deferred Work
+
+- **Guest seams are absent in the harness** — `hooks`, `mcp`, and `settings` report `skipped` unless a deployment supplies the guest seam. There is no harness-owned `ctx.mcp` or `ctx.hooks` service today.
+- **Agent providers forward execution** — the agents provider names its backend (default `fork`) and delegates `start`; executing a CC agent requires a `fork` backend on the subagent seam at run time.
+- **Skill activation is host-driven** — the loader registers the wiring and activation descriptors; applying them at the model-facing moment is the host's responsibility.

package/README.zh.md

@@ -0,0 +1,45 @@
+# @jianxx/dsh-cc-plugin-loader
+
+[English](README.md) | 中文
+
+加载 Claude Code 插件的 `plugin.json` 清单，并把每个组件挂载为内存中的 dsh 插件。
+
+这个兼容性加载器读取 CC 插件清单子集，用 [`@jianxx/dsh-cc-skill-loader`](../../skill/skill-claude-code/README.md) 与 [`@jianxx/dsh-cc-claude-code-agents`](../../preset/claude-code-agents/README.md) 的纯函数翻译每个组件，并通过 `ctx.get(...)` 读取该组件的宿主 seam。它不是运行时：它产出类型化挂载与结构化报告，把执行交给它注册到的 seam。
+
+## 加载器
+
+`mountCcPlugin(ctx, { root, seams? })` 读取 `${root}/plugin.json`、校验清单子集，并把每个存在的组件作为 Cordis effect 挂载。它返回 `{ report, dispose }`——`report` 是每个组件的加载结果，`dispose` 回收所有已挂载组件（context 卸载时自动调用）。
+
+### 清单子集
+
+加载器校验 `name`（必填、kebab-case）、`version`、`description`、`author`，以及组件字段 `commands`、`agents`、`skills`、`hooks`、`mcpServers`、`settings`。格式错误的清单会在加载时携带插件名抛错。未知的顶层字段被忽略，与 Claude Code 的宽容处理一致。
+
+### 组件及其 seam
+
+每个组件都是 peer 风格：加载器通过 `ctx.get(...)` 探测宿主 seam，当该 seam 缺失时把组件报告为 `skipped`（绝不让整个加载失败）。
+
+| 组件 | 来源 | Seam（探测） | 翻译 |
+|---|---|---|---|
+| `commands` | 清单内联或 source | `commands` | 通过 `register` 注册每个斜杠命令；handler 返回命令内容 |
+| `agents` | `agents/` 目录或清单路径 | `subagents` | 通过 `loadAgentsDir` 加载 `AgentDefinition`，再通过 `registerProvider` 注册为命名 provider |
+| `skills` | `skills/` 目录或清单路径 | `skills` | 通过 `discoverCcSkills` 发现 `SKILL.md`、解析 frontmatter，再通过 `register` 注册为运行时技能 |
+| `hooks` | `hooks/hooks.json` 或内联 | `hooks`（guest）| 通过 `mergePluginHooks` 注入按事件组织的 hook 映射 |
+| `mcpServers` | 内联记录或 `.mcp.json` | `mcp`（guest）| 通过 `registerServer` 注册每个 server（工具命名是 seam 的职责）|
+| `settings` | 清单记录 | `settings`（guest）| 过滤到 allowlist（当前是 `agent`）后通过 `set` 写入 |
+
+`hooks` 与 `mcp` seam 目前没有 harness 自有的服务；希望挂载这些组件的部署应提供 guest seam，否则它们会被报告为 `skipped`。
+
+## 技能语义接线
+
+在技能挂载之上，本包是把 `skill-claude-code` 的 metadata 转成可执行注册的 consumer：
+
+- **`allowed-tools`** —— `skillToolRestriction(metadata)` 构建仅允许的 `tools.restrict()` 过滤器；`applySkillRestriction(metadata, agent)` 把它应用到 scoped agent 并返回 disposer。
+- **`context: fork`** —— `resolveSkillExecution(metadata, subagentsPresent)` 把技能路由到子代理执行；当 subagent seam 缺失时降级为内联并被报告。
+- **`paths`** —— `registerSkillPathActivator(ctx, skill, projectRoot)` 挂上用于条件激活的 `fs/observed` 路径激活器。
+- **内联 shell** —— `activationFor(metadata, subagentsPresent)` 报告 `forbidInlineShell`（`shell: false` 的技能不得开启内联 shell）。
+
+## 已知限制与待办工作
+
+- **harness 中缺少 guest seam** —— 除非部署提供 guest seam，否则 `hooks`、`mcp`、`settings` 会报告为 `skipped`。当前没有 harness 自有的 `ctx.mcp` 或 `ctx.hooks` 服务。
+- **agent provider 转发执行** —— agents provider 以名字命名其后端（默认 `fork`）并委托 `start`；执行 CC agent 需要 subagent seam 在运行时存在 `fork` 后端。
+- **技能激活由宿主驱动** —— 加载器注册接线与激活描述符；在模型可见的时刻应用它们由宿主负责。

package/lib/agents.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Mount a Claude Code plugin's sub-agent definitions.
+ *
+ * Loads `AgentDefinition`s from the plugin's standard `agents/` directory and
+ * any inline manifest `agents` paths via the claude-code-agents loader, then
+ * registers each as a named subagent provider backing `context: fork`. The
+ * provider is a thin forwarder: `start` resolves a named execution backend on
+ * the subagent seam (default `fork`) and delegates, overlaying the agent's
+ * system prompt, model, and tool restriction. Registration is effect-scoped so
+ * unmounting the plugin removes every agent.
+ *
+ * @module
+ */
+import type { AgentDefinition } from '@jianxx/dsh-cc-claude-code-agents';
+import type { CcPluginManifest } from './types.ts';
+import { ComponentTally } from './seams.ts';
+/**
+ * Resolve a frontmatter `model` into a dsh `{provider, model}` route at spawn
+ * time. Returns `undefined` meaning "no override" (the child inherits the
+ * parent's route). When the function is absent, providers keep the historical
+ * byte-identical behavior of overlaying the literal model id. The optional
+ * fields admit explicit `undefined` (per-field inheritance), matching the
+ * `ResolvedRoute` shape from `@jianxx/dsh-cc-model-aliases`.
+ */
+export type ResolveModel = (model: string | undefined) => {
+    readonly provider?: string | undefined;
+    readonly model?: string | undefined;
+} | undefined;
+/** The subagent seam: a named-provider registry with a backend resolver. */
+export interface SubagentsSeam {
+    /**
+     * Register a named execution provider.
+     * @param provider - the provider to register.
+     * @returns the exact disposer that removes the provider.
+     */
+    registerProvider(provider: unknown): () => void;
+    /** Look up a provider by name, for backend resolution at `start`. */
+    getProvider(name: string): unknown | undefined;
+}
+/** The execution backend a CC agent provider forwards to. */
+export interface SubagentBackend {
+    /** Start a one-shot child run against a delegation request. */
+    start(request: unknown): Promise<unknown>;
+}
+/** A thin forwarder provider: overlays an AgentDefinition and delegates. Exported for the cc-shell bundle's base-agent glue. */
+export declare class AgentProvider implements SubagentBackend {
+    private readonly definition;
+    private readonly resolve;
+    private readonly resolveModel?;
+    private readonly backendName;
+    constructor(definition: AgentDefinition, resolve: (name: string) => SubagentBackend | undefined, resolveModel?: ResolveModel | undefined);
+    /** Register-time provider name; `start` forwards to the backend. */
+    get name(): string;
+    /** The start-time features this agent's definition requires. */
+    get capabilities(): {
+        outputSchema: boolean;
+        depthLimit: boolean;
+        toolFilter: boolean;
+        persona: boolean;
+    };
+    /** Whether the child sees the parent's completed-turn prefix. */
+    get inheritsParentContext(): boolean;
+    /**
+     * Delegate a delegation request to the resolved backend, overlaying the
+     * agent's system prompt, model, and tool restriction.
+     * @param request - the delegating request forwarded from the seam.
+     * @returns the backend's run handle.
+     * @throws when no backend is resolvable (execution depends on the host).
+     */
+    start(request: unknown): Promise<unknown>;
+    /**
+     * Compute the `agentOptions` model override for one spawn.
+     *
+     * With no resolver injected this is byte-identical to the historical
+     * behaviour: overlay the literal frontmatter `model` id. With a resolver
+     * injected, the resolver's return is honored directly — a route overlays its
+     * defined fields (per-field inheritance preserved by dropping `undefined`),
+     * and `undefined` means "no override", so `inherit`/unconfigured-builtin
+     * resolve to inheriting the parent route rather than re-overlaying the
+     * literal model.
+     * @returns the model/provider override, or `undefined` for no override.
+     */
+    private resolveModelOverride;
+}
+/** Agents live under this directory in a plugin root, when present. */
+export declare const STANDARD_AGENTS_DIR = "agents";
+/** Options for mounting one plugin's agents. */
+export interface MountAgentsOptions {
+    /** The plugin root directory; standard `agents/` resolves against it. */
+    readonly pluginRoot: string;
+    /** The parsed manifest, whose `agents` paths add extra agent files. */
+    readonly manifest: CcPluginManifest;
+    /** The subagent seam (probed; `undefined` to skip agents). */
+    readonly subagents: SubagentsSeam | undefined;
+    /** Optional plugin manifest-name prefix applied to each agent type. */
+    readonly namespacePrefix?: string;
+    /** Optional spawn-time model resolver threaded into every provider. */
+    readonly resolveModel?: ResolveModel;
+}
+/**
+ * Load and register a plugin's sub-agent definitions.
+ * @param options - plugin root, manifest, and the subagent seam.
+ * @returns mounted disposers and per-component counts.
+ */
+export declare function mountAgents(options: MountAgentsOptions): Promise<{
+    disposers: (() => void)[];
+    tally: ComponentTally;
+}>;
+//# sourceMappingURL=agents.d.ts.map

package/lib/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAA;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,SAAS,CAAA;AAErJ,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,IAAI,CAAA;IAC/C,qEAAqE;IACrE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CAC/C;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC1C;AAED,gIAAgI;AAChI,qBAAa,aAAc,YAAW,eAAe;IAIjD,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IALhC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGlB,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,eAAe,GAAG,SAAS,EACtD,YAAY,CAAC,EAAE,YAAY,YAAA;IAG9C,oEAAoE;IACpE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gEAAgE;IAChE,IAAI,YAAY,IAAI;QAAE,YAAY,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAOxG;IAED,iEAAiE;IACjE,IAAI,qBAAqB,IAAI,OAAO,CAEnC;IAED;;;;;;OAMG;IACG,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB/C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,oBAAoB;CAc7B;AAED,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,WAAW,CAAA;AAE3C,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,CAAA;IAC7C,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CACrC;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC,CAmB5H"}

package/lib/agents.js

@@ -0,0 +1,147 @@
+/**
+ * Mount a Claude Code plugin's sub-agent definitions.
+ *
+ * Loads `AgentDefinition`s from the plugin's standard `agents/` directory and
+ * any inline manifest `agents` paths via the claude-code-agents loader, then
+ * registers each as a named subagent provider backing `context: fork`. The
+ * provider is a thin forwarder: `start` resolves a named execution backend on
+ * the subagent seam (default `fork`) and delegates, overlaying the agent's
+ * system prompt, model, and tool restriction. Registration is effect-scoped so
+ * unmounting the plugin removes every agent.
+ *
+ * @module
+ */
+import { join, resolve } from 'node:path';
+import { loadAgentsDir } from '@jianxx/dsh-cc-claude-code-agents';
+import { ComponentTally } from "./seams.js";
+/** A thin forwarder provider: overlays an AgentDefinition and delegates. Exported for the cc-shell bundle's base-agent glue. */
+export class AgentProvider {
+    definition;
+    resolve;
+    resolveModel;
+    backendName = 'fork';
+    constructor(definition, resolve, resolveModel) {
+        this.definition = definition;
+        this.resolve = resolve;
+        this.resolveModel = resolveModel;
+    }
+    /** Register-time provider name; `start` forwards to the backend. */
+    get name() {
+        return this.definition.agentType;
+    }
+    /** The start-time features this agent's definition requires. */
+    get capabilities() {
+        return {
+            outputSchema: false,
+            depthLimit: false,
+            toolFilter: this.definition.toolRestriction !== undefined,
+            persona: this.definition.permissionMode !== undefined || this.definition.isolation !== undefined,
+        };
+    }
+    /** Whether the child sees the parent's completed-turn prefix. */
+    get inheritsParentContext() {
+        return true;
+    }
+    /**
+     * Delegate a delegation request to the resolved backend, overlaying the
+     * agent's system prompt, model, and tool restriction.
+     * @param request - the delegating request forwarded from the seam.
+     * @returns the backend's run handle.
+     * @throws when no backend is resolvable (execution depends on the host).
+     */
+    async start(request) {
+        const backend = this.resolve(this.backendName);
+        if (backend === undefined) {
+            throw new Error(`cc-plugin-loader: no "${this.backendName}" subagent backend is registered to run agent "${this.definition.agentType}"`);
+        }
+        const delegation = request;
+        const modelOverride = this.resolveModelOverride();
+        return backend.start({
+            ...delegation,
+            prompt: this.definition.systemPrompt,
+            ...modelOverride !== undefined
+                ? { agentOptions: { ...delegation['agentOptions'], ...modelOverride } }
+                : {},
+            ...this.definition.toolRestriction !== undefined ? { toolFilter: this.definition.toolRestriction } : {},
+        });
+    }
+    /**
+     * Compute the `agentOptions` model override for one spawn.
+     *
+     * With no resolver injected this is byte-identical to the historical
+     * behaviour: overlay the literal frontmatter `model` id. With a resolver
+     * injected, the resolver's return is honored directly — a route overlays its
+     * defined fields (per-field inheritance preserved by dropping `undefined`),
+     * and `undefined` means "no override", so `inherit`/unconfigured-builtin
+     * resolve to inheriting the parent route rather than re-overlaying the
+     * literal model.
+     * @returns the model/provider override, or `undefined` for no override.
+     */
+    resolveModelOverride() {
+        const model = this.definition.model;
+        const resolver = this.resolveModel;
+        if (resolver === undefined) {
+            return model !== undefined ? { model } : undefined;
+        }
+        if (model === undefined)
+            return undefined;
+        const route = resolver(model);
+        if (route === undefined)
+            return undefined;
+        const out = {};
+        if (route.provider !== undefined)
+            out.provider = route.provider;
+        if (route.model !== undefined)
+            out.model = route.model;
+        return out;
+    }
+}
+/** Agents live under this directory in a plugin root, when present. */
+export const STANDARD_AGENTS_DIR = 'agents';
+/**
+ * Load and register a plugin's sub-agent definitions.
+ * @param options - plugin root, manifest, and the subagent seam.
+ * @returns mounted disposers and per-component counts.
+ */
+export async function mountAgents(options) {
+    const tally = new ComponentTally('agents');
+    const disposers = [];
+    if (options.subagents === undefined) {
+        tally.addSkipped('subagent seam "subagents" is not mounted');
+        return { disposers, tally };
+    }
+    const definitions = await loadAgentDefinitions(options.pluginRoot, options.manifest);
+    if (definitions.length === 0) {
+        tally.addSkipped('plugin ships no agents directory or manifest agents paths');
+        return { disposers, tally };
+    }
+    const subagents = options.subagents;
+    for (const definition of definitions) {
+        const provider = new AgentProvider(definition, name => subagents.getProvider(name), options.resolveModel);
+        disposers.push(subagents.registerProvider(provider));
+        tally.addLoaded();
+    }
+    return { disposers, tally };
+}
+/** Load agent definitions from the standard `agents/` dir and manifest paths. */
+async function loadAgentDefinitions(pluginRoot, manifest) {
+    const dirs = [join(pluginRoot, STANDARD_AGENTS_DIR)];
+    const extra = manifest.agents.map((path) => {
+        const resolved = resolve(pluginRoot, path);
+        // An inline path may name one `.md`/`.json` file; load its parent dir.
+        return /\.(md|json)$/.test(resolved) ? dirname(resolved) : resolved;
+    });
+    dirs.push(...extra);
+    const byName = new Map();
+    for (const dir of dirs) {
+        for (const agent of await loadAgentsDir(dir, 'project')) {
+            byName.set(agent.agentType, agent);
+        }
+    }
+    return Array.from(byName.values());
+}
+function dirname(path) {
+    const index = path.lastIndexOf('/');
+    return index === -1 ? '.' : path.slice(0, index);
+}
+//# sourceMappingURL=agents.js.map

package/lib/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}

package/lib/commands.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Mount a Claude Code plugin's slash commands.
+ *
+ * Translates manifest `commands` entries (inline content or a source file) into
+ * typed command definitions registered on the commands seam. Each handler
+ * returns the command's rendered content, so invoking `/name` surfaces the
+ * plugin author's instructions. Registration is effect-scoped.
+ *
+ * @module
+ */
+import type { CcPluginManifest } from './types.ts';
+import { ComponentTally } from './seams.ts';
+/** The commands seam: accepts a typed slash-command definition. */
+export interface CommandsSeam {
+    /**
+     * Register one command definition.
+     * @param definition - the command to register.
+     * @returns the exact disposer that removes the command.
+     */
+    register(definition: CommandDefinition): () => void;
+}
+/** The minimal typed command definition this loader emits. */
+export interface CommandDefinition {
+    /** Lowercase kebab command name. */
+    readonly name: string;
+    /** Human-readable description. */
+    readonly description: string;
+    /** Prompts the command's execution (returns content). */
+    readonly handler: () => CommandResult | Promise<CommandResult>;
+}
+/** Result shape the loader's command handlers return. */
+export type CommandResult = {
+    readonly kind: 'success';
+    readonly text?: string;
+};
+/** Commands live under this directory in a plugin root, when present. */
+export declare const STANDARD_COMMANDS_DIR = "commands";
+/** Options for mounting one plugin's commands. */
+export interface MountCommandsOptions {
+    /** The plugin root directory; inline `source` paths resolve against it. */
+    readonly pluginRoot: string;
+    /** The parsed manifest, whose `commands` field drives registration. */
+    readonly manifest: CcPluginManifest;
+    /** The commands seam (probed; `undefined` to skip commands). */
+    readonly commands: CommandsSeam | undefined;
+}
+/**
+ * Register a plugin's manifest commands.
+ * @param options - plugin root, manifest, and the commands seam.
+ * @returns mounted disposers and per-component counts.
+ */
+export declare function mountCommands(options: MountCommandsOptions): {
+    disposers: (() => void)[];
+    tally: ComponentTally;
+};
+//# sourceMappingURL=commands.d.ts.map

package/lib/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAa,MAAM,YAAY,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAA;CACpD;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC/D;AAED,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhF,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,aAAa,CAAA;AAE/C,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAA;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG;IAAE,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CA4BjH"}