@dsh-enhanced/assistant-policy 0.1.64 → 0.1.66

package/README.md

@@ -142,7 +142,7 @@ DSH 原生 `user-approval` 仍只负责 open turn 内的即时询问；本插件
 - 文件系统：创建一个 SQLite 数据库及 WAL/SHM 辅助文件；新目录权限 `0700`，主数据库 `0600`。数据库使用 WAL、`busy_timeout`、外键、FULL synchronous 和前向 schema 版本。
 - 网络：插件不直接打开 socket；启用隔离自动 reviewer 时会调用宿主 `dsh-llm`，所选 provider route 可能使用网络。provider 的认证与传输仍由宿主拥有，本插件不直接读取其凭据。
 - 子进程：无。
-- 凭据：运行时的 Policy service 不读取或保存凭据值。审计按敏感 key/value、shell `command`、授权头、token、password、path/cwd 做脱敏，资源 id 仅保存 SHA-256。自动 reviewer 输入只要需要任何 secret 脱敏就失去自动放行资格并转人工。包另附带两个安装期 CLI（`dsh-permission-setup`、`dsh-model-setup`），仅供安装器/部署者手动调用，不在 Cordis 运行时加载。安装器始终传 `--profile <name>`：两个 CLI 先校验所选 DSH Host 并读取目标 profile 的原生 `--dump-config`，再原子改写其 `cordis.patch.yml`，分别写入 `permission.defaultPreset` 与 `agent-default-model`（自定义网关还写入 `llm-pi-ai.providers.<route>`），保留原生有效整段配置中的其它预设、网关、注释和 `!!js`。读取或组合失败时拒绝写入。若省略 `--profile`，CLI 仍写旧版全局 `settings.yaml`；DSH 0.2 在下次启动时把它一次性导入第一个启动的 profile，不适合多 profile 设置。目标配置对应区段尚留在 `settings.yaml` 时，显式 `--profile` 拒绝写入，须先把旧设置迁移至目标 profile，避免首启覆盖。显式 `--store-key` 时 API Key 仅从环境变量读取，原子写入 `$DSH_HOME/.credentials.yaml`（`0600`，目录 `0700`），密钥绝不作为命令行参数、缺失时 fail-closed。agent route（如 `traex-agent`）不涉及 API Key；`--enable-in-profile` 与 `--profile` 同时使用时必须同名。
+- 凭据：运行时的 Policy service 不读取或保存凭据值。审计按敏感 key/value、shell `command`、授权头、token、password、path/cwd 做脱敏，资源 id 仅保存 SHA-256。自动 reviewer 输入只要需要任何 secret 脱敏就失去自动放行资格并转人工。包另附带三个安装期 CLI（`dsh-permission-setup`、`dsh-model-setup`、`dsh-plugin-setup`），仅供安装器/部署者手动调用，不在 Cordis 运行时加载。`dsh-plugin-setup` 见下方[插件配置 CLI](#插件配置-clidsh-plugin-setup)。安装器始终传 `--profile <name>`：前两个 CLI 先校验所选 DSH Host 并读取目标 profile 的原生 `--dump-config`，再原子改写其 `cordis.patch.yml`，分别写入 `permission.defaultPreset` 与 `agent-default-model`（自定义网关还写入 `llm-pi-ai.providers.<route>`），保留原生有效整段配置中的其它预设、网关、注释和 `!!js`。读取或组合失败时拒绝写入。若省略 `--profile`，CLI 仍写旧版全局 `settings.yaml`；DSH 0.2 在下次启动时把它一次性导入第一个启动的 profile，不适合多 profile 设置。目标配置对应区段尚留在 `settings.yaml` 时，显式 `--profile` 拒绝写入，须先把旧设置迁移至目标 profile，避免首启覆盖。显式 `--store-key` 时 API Key 仅从环境变量读取，原子写入 `$DSH_HOME/.credentials.yaml`（`0600`，目录 `0700`），密钥绝不作为命令行参数、缺失时 fail-closed。agent route（如 `traex-agent`）不涉及 API Key；`--enable-in-profile` 与 `--profile` 同时使用时必须同名。
 
 自动发现本机 agent 时可调用 `dsh-model-setup --profile web --provider traex-agent --enable-in-profile web --enable-only [--agent-command /absolute/path/to/traex]`：仅启用目标 profile 的 route，不改模型选择。若希望在没有显式选择时把它设为该 profile 的默认模型，改用 `--default-if-absent`；CLI 用 YAML AST 检查待导入的 `settings.yaml`、home patch 和目标 profile patch，已有 `agent-default-model` 就保留，三处都没有才在目标 profile patch 添加默认模型行。两个模式互斥且仅适用于带 `--enable-in-profile` 的 agent route；启用 route 时在目标行同时写 `disabled: false` 和 `config.enabled: true`，保留 profile 的已有配置；没有 profile 配置时继承 home patch 最后生效的整段配置，并保留 `!!js` 表达式。`--agent-command` 必须是绝对路径，只填缺失的 `config.command`，保留已有 `command` 和 `cwd`。显式 model setup 传 `--profile` 时只设置目标 profile；不传时保留旧版 `settings.yaml` 行为。
 - 浏览器：无。
@@ -156,7 +156,7 @@ DSH 原生 `user-approval` 仍只负责 open turn 内的即时询问；本插件
 
 ### Finite action broker preauthorization
 
-`evaluateAgent` checks live identity and rules without consuming budgets or recording authorization; the broker charges `authorizeAgent` once before credential acquisition and dispatch with a durable action ID as its idempotency key. Polling must use the read-only method. `registerPreauthorizedTool` accepts only exact definitions from their owning trusted Fibers: the approved GitHub action tools from `dsh-enhanced-assistant-actions`, `isolation_run`/`isolation_grants` from Isolation, the approved Goals tools from Goals, and `skill_run`/`skill_status` from Skills. The registration expires with the caller scope; same-name scoped shadows cannot borrow it. This skips native per-call approval only when the owned predicate remains valid. Monotonic policy denials, cancellation, revocation and other tool middleware still apply. It is a trusted Host integration contract, not isolation against malicious plugins in the same Host process.
+`evaluateAgent` checks live identity and rules without consuming budgets or recording authorization; the broker charges `authorizeAgent` once before credential acquisition and dispatch with a durable action ID as its idempotency key. Polling must use the read-only method. `registerPreauthorizedTool` accepts only exact definitions from their owning trusted Fibers: the approved GitHub action tools from `dsh-enhanced-assistant-actions`, `isolation_run`/`isolation_grants` from Isolation, the approved Goals tools from Goals, `skill_run`/`skill_status` from Skills, and the explicitly listed WorkItems tools from `AssistantWorkItemsService`. The registration expires with the caller scope; same-name scoped shadows cannot borrow it. This skips native per-call approval only when the owned predicate remains valid. Monotonic policy denials, cancellation, revocation and other tool middleware still apply. It is a trusted Host integration contract, not isolation against malicious plugins in the same Host process.
 
 `assistant-isolation` may also register only its exact `isolation_run` ToolDefinition for finite-grant risk preauthorization. This suppresses a redundant approval prompt, while native tool Policy denials and call budgets remain effective. Isolation separately authorizes `tool:isolation:<grant-id>` once per new job with a persistent idempotency key; polling and result replay do not consume that grant-operation budget. A separately configured `tool:isolation_run` budget continues to count tool calls. See the [Isolation authorization contract](../assistant-isolation/README.md).
 
@@ -164,4 +164,64 @@ DSH 原生 `user-approval` 仍只负责 open turn 内的即时询问；本插件
 
 `assistant-goals` can register only its exact `goal_checkpoint` definition when the separate checkpoint capability is present. Its predicate is read-only and requires a live authenticated owner, the owning Session/native Goal, the current record version, and a valid same-owner dependency graph; the execution path repeats Policy and transactional CAS checks. A caller Fiber disposal, cancellation, policy denial, stale version, or definition mismatch fails closed.
 
+`workItemToolPreauthorizationVersion() === 1` lets only the owning `AssistantWorkItemsService` Fiber register its exact `work_item_claim`, `work_item_report`, `work_item_status`, `work_item_read_report`, `work_item_list` and `work_item_recall` definitions. The first four are worker tools. WorkItems checks the frozen production occurrence, persisted item, current owner version/generation, scope, expiry, original admission Policy and bounded tool arguments without changing its ledger; tool execution repeats those checks after any approval wait. Legacy items and calls without a proven mandate retain the ordinary approval fallback, which cannot extend the execution authority. A nested Policy injection withdraws these registrations when Policy is replaced or unloaded. See [the WorkItems preauthorization contract](../assistant-work-items/README.md#已准入工作项的工具预授权).
+
+The optional foreground `work_item_list` and `work_item_recall` tools instead require Delivery proof of the current owner and exact live human-turn tool call, plus the separate `inspect-work-items` permission for the configured worker automation. Their preauthorization and final fences use read-only `evaluateAgent`; actual reads charge `authorizeAgent` with a stable call-bound idempotency key. This permission can read same-owner historical tasks across Session generations, including expired or withdrawn tasks, but cannot claim, resume or renew their execution authority. Background workers cannot use it to inspect other tasks. A read-only linked alias (work-items `ownerRecall.linkedAliases`) is instead charged through `authorizeAgentForPrincipal(agent, action, resource, { idempotencyKey, principal })`: same identity and rule evaluation as `authorizeAgent`, but `principal` must equal the principal bound to that Agent (else `budget-principal-mismatch`, audited, nothing charged), and a matched rule budget is reserved in the ledger scope `principalPartitionScope(baseScope, principal)` (`principal-partition/v1:[baseScope, principal]`) with the budget's own limit and period, so the alias never spends the owner's quota. Rules are evaluated first, so rule, default-deny and emergency-stop denials carry exactly the reason `authorizeAgent` would return; only an otherwise-allowed request is denied for a principal mismatch. No denial charges a budget, and every outcome is audited. The decision carries `budgetPrincipal` only when such a charge happened. There is no cross-partition aggregate cap: each distinct principal gets the full limit, so a caller must bound the principal set itself (WorkItems bounds it to the owner plus at most 8 allowlisted aliases, i.e. at most 9 × limit). Additive API; no ledger schema change.
+
 For native skill benchmark cells, `delegatedSkillToolPreauthorizationVersion() === 1` allows only the actual Skills Fiber to register its exact `skill_run` and `skill_status` definitions. Their predicate requires a live owner-bound delegated arm whose steps are all `isolation_run`; ordinary skills, different versions, revoked mounts and foreign scopes do not gain this authorization. Native Policy, call budgets and each nested tool check remain active. See [native skill reuse](../../docs/native-skill-reuse.md).
+
+### WorkItem Growth 的有限 create-only 预授权
+
+`workItemGrowthToolPreauthorizationVersion()` 仅在当前 Policy generation 活跃时返回 `1`。`registerPreauthorizedTool` 允许 `dsh-enhanced-assistant-growth-driver` Fiber 为四个精确工具定义注册实时 predicate：`plugin_source_gaps`、`plugin_source_read`、`plugin_source_create`、`plugin_source_job_status`。不接受同名伪造定义、其他 Fiber、`growth_*` 别名、prepare、targets 或 revise 工具；注册随拥有它的 Cordis effect 释放；返回的 disposer 会同时撤销 grant 并移除 Fiber 上的 effect，重复调用仍幂等，常驻 Growth Fiber 的连续 run 不累积捕获旧 Agent/definition 的注册。
+
+Growth 调用方仍须独立核验显式启用的 WorkItem v2 run、真实来源、owner、工具 realm、期限和有限额度。Policy 不由工具名称推定这些授权，也不授予通用 create 权限。带 `denialReason` 的 predicate 拒绝或抛错会直接拒绝，不能转人工审批延长冻结授权；普通独立 Policy deny、预算、紧急停止和工具 guard 始终保留。本入口不修改 Approval 配置、不生成额外批准票据，也不扩大候选工具范围。
+
+## 插件配置 CLI（dsh-plugin-setup）
+
+`dsh-plugin-setup` 在单个 profile 上列出、启用、停用和修改已安装 `@dsh-enhanced/*` 插件，写入 `$DSH_HOME/profiles/<p>/cordis.patch.yml`。它不安装包（安装用 `dsh plugin --profile <p> add <pkg>`），也不在运行时加载。
+
+```sh
+bin=~/.dsh/profiles/web/node_modules/.bin/dsh-plugin-setup
+$bin                                   # 终端内为引导菜单，否则等同 list
+$bin list
+$bin show work-items                   # 有效配置，秘密值显示为 [redacted]
+$bin enable work-items                 # 行 disabled 门与配置 enabled 同时打开
+$bin disable event-triggers
+$bin set delivery maxAttempts 9        # 按当前值类型校验
+$bin set work-items intakeLedger.enabled true
+$bin unset delivery maxAttempts        # 回到包默认值
+$bin preset recommended --dry-run      # 先看计划
+$bin preset recommended --yes
+```
+
+插件可写短名（`work-items`）、包名或行 id。只有一个 profile 时自动选中，否则需 `--profile`（或 `DSH_PROFILE`）；`--dsh-home` 默认 `DSH_HOME` / `~/.dsh`。`--json` 输出结构化结果，`--dry-run` 不写文件。改动在下次 `dsh-rsi restart --profile <p>` 后生效。
+
+行为：
+
+- 读取与校验：先校验选定 Host 为已批准版本并读取原生 `--dump-config`。Cordis 中行级 `config` 整段替换继承配置，所以首次编辑会从有效配置完整克隆该行，保留注释、其它行与 `!!js`。
+- 值校验：按当前值类型转换（布尔、数字、字符串、JSON 对象/数组）；未知 key 和 `!!js` 值需 `--force`，少数可选开关（如 `work-items.mode`、`intakeLedger.enabled`、`delivery.attentionAttachOverCap`、`evaluation.notificationOutcomesEnabled`、`event-triggers.pollerEnabled`）已登记，无需 `--force`。
+- 写入：`0600` 临时文件原子替换，再次 dump 核对每项改动真实生效；失败即恢复原文件（或删除新建文件）并报错。
+- 拒绝项（`--force` 也不放开）：修改 `assistant-policy` 与 `plugin-control-plane` 配置；停用 `assistant-policy`；写入 secret/password/token/apiKey 等秘密 key（凭据用对应 `*Handle` 或专用 setup CLI）；修改 Delivery `ownerRoutes`、`policyRef` 授权 key；在占位 tenant/appId 下启用 lark-channel（改用 `dsh-lark-setup`）；启用缺少 `workerAutomationId` 或 `scope` 的 active 模式 work-items。
+- 不改任何权限默认值，不改 owner 认证、密封验证或凭据处理。
+
+### recommended 预设
+
+`preset recommended` 一次打开以下默认关闭的可选功能，仅作用于已安装且已加载的插件，其余记为 skipped，可重复执行：
+
+| 插件 | 写入 |
+| --- | --- |
+| `assistant-work-items` | `enabled: true`、`intakeLedger.enabled: true`（`mode` 保持 `observe`；若已设 active 且尚未启用则跳过） |
+| `assistant-delivery` | `attentionAttachOverCap: true` |
+| `assistant-evaluation` | `notificationOutcomesEnabled: true` |
+| `event-triggers` | `pollerEnabled: true` |
+
+包默认值不变。onboarding 等程序可直接调用：
+
+```ts
+import { applyRecommendedPluginPreset } from '@dsh-enhanced/assistant-policy/plugin-setup'
+
+const result = await applyRecommendedPluginPreset({ dshHome, profile }, { dryRun: false })
+// result: { profile, patchPath, changed, dryRun, changes: [{ id, key, from, to }], skipped: [{ id, reason }] }
+```
+
+安装脚本可用 `scripts/install/common.sh` 中的 `dsh_enhanced_apply_plugin_preset <profile> <dsh_home> <dry_run> [preset]`，没有场景会隐式调用它。

package/bin/dsh-plugin-setup.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runPluginSetup } from '../lib/plugin-setup.js'
+
+void runPluginSetup().catch(error => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  process.exitCode = 1
+})

package/lib/index.d.ts

@@ -10,7 +10,8 @@ export type { HumanApprovalAnswerer } from './approval-routing.js';
 export { isAutoReviewEscalation } from './auto-review.js';
 export type { AutoReviewAssessment, AutoReviewConfig } from './auto-review.js';
 export { AUTO_REVIEW_APPROVAL_REASON, HUMAN_APPROVAL_REASON } from './tool-risk.js';
-export type { NativeFullReviewerReconciliation, OwnerRequestedChangeContext, OwnerRequestedChangeInput, PolicyBudgetConfig, PolicyHostConfiguration } from './service.js';
+export type { NativeFullReviewerReconciliation, OwnerRequestedChangeContext, OwnerRequestedChangeInput, PolicyBudgetConfig, PolicyHostConfiguration, PrincipalAuthorizationOptions } from './service.js';
+export { principalPartitionScope } from './service.js';
 export { APPROVAL_DISPLAY_BUDGET } from './ledger.js';
 export { ApprovalSettlementConflict, validateApprovalSettlement } from './settlement.js';
 export type { ApprovalSettlementConflictReason, ApprovalSettlementExpectation, ValidatedApprovalSettlement, } from './settlement.js';

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,eAAO,MAAM,IAAI,kCAAkC,CAAA;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;AAClD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,wCAAwC,EAAE,MAAM,iCAAiC,CAAA;AAC1F,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AACzD,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC9E,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACnF,YAAY,EAAE,gCAAgC,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACzK,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAA;AACxF,YAAY,EACV,gCAAgC,EAChC,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,EACrB,2BAA2B,EAC3B,6BAA6B,EAC7B,8BAA8B,EAC9B,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC3B,sBAAsB,EACtB,UAAU,EACV,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,aAAa,CAAA;AACpB,cAAc,YAAY,CAAA;AAE1B,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,cAAc,EAAE,MAAM,GAAG,IAAI,CAE/E;AAED,eAAe,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,eAAO,MAAM,IAAI,kCAAkC,CAAA;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;AAClD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,wCAAwC,EAAE,MAAM,iCAAiC,CAAA;AAC1F,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AACzD,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC9E,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACnF,YAAY,EAAE,gCAAgC,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAA;AACxM,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAA;AACxF,YAAY,EACV,gCAAgC,EAChC,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,EACrB,2BAA2B,EAC3B,6BAA6B,EAC7B,8BAA8B,EAC9B,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC3B,sBAAsB,EACtB,UAAU,EACV,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,aAAa,CAAA;AACpB,cAAc,YAAY,CAAA;AAE1B,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,cAAc,EAAE,MAAM,GAAG,IAAI,CAE/E;AAED,eAAe,sBAAsB,CAAA"}

package/lib/index.js

@@ -6,6 +6,7 @@ export { APPROVAL_REVIEWERS, approvalReviewerOf, foldApprovalReviewer, getApprov
 export { waitForApprovalReviewerSessionEventReady } from './session-event-registration.js';
 export { isAutoReviewEscalation } from './auto-review.js';
 export { AUTO_REVIEW_APPROVAL_REASON, HUMAN_APPROVAL_REASON } from './tool-risk.js';
+export { principalPartitionScope } from './service.js';
 export { APPROVAL_DISPLAY_BUDGET } from './ledger.js';
 export { ApprovalSettlementConflict, validateApprovalSettlement } from './settlement.js';
 export * from './types.js';

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,IAAI,GAAG,+BAA+B,CAAA;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;AAClD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,wCAAwC,EAAE,MAAM,iCAAiC,CAAA;AAE1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAEzD,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAEnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAA;AA4BxF,cAAc,YAAY,CAAA;AAE1B,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,MAAqC;IACvE,IAAI,sBAAsB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;AACzC,CAAC;AAED,eAAe,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,IAAI,GAAG,+BAA+B,CAAA;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;AAClD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,wCAAwC,EAAE,MAAM,iCAAiC,CAAA;AAE1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAEzD,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAEnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAA;AA4BxF,cAAc,YAAY,CAAA;AAE1B,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,MAAqC;IACvE,IAAI,sBAAsB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;AACzC,CAAC;AAED,eAAe,sBAAsB,CAAA"}

package/lib/plugin-setup.d.ts

@@ -0,0 +1,137 @@
+import { type EffectiveProfileDumpReader } from './profile-setup.js';
+export interface PluginSetupTarget {
+    dshHome: string;
+    /** Omit to use `DSH_PROFILE` or the only profile under `$DSH_HOME/profiles`. */
+    profile?: string;
+}
+export interface PluginSetupOptions {
+    /** Test seam; defaults to the approved Host `--dump-config`. */
+    readDump?: EffectiveProfileDumpReader;
+    /** Compute and report the change without writing. */
+    dryRun?: boolean;
+}
+export interface ProfilePluginSummary {
+    id: string;
+    slug: string;
+    packageName: string;
+    /** Loader row gate (`disabled: true` means the plugin is not loaded). */
+    loaded: boolean;
+    /** Top-level `enabled` config gate when the plugin has one. */
+    enabled?: boolean;
+    /** Feature flags: top-level `*Enabled` booleans and one-level `<key>.enabled`. */
+    flags: Record<string, boolean>;
+    /** True when the profile patch already overrides this row. */
+    overridden: boolean;
+}
+export interface PluginChange {
+    id: string;
+    key: string;
+    from: unknown;
+    to: unknown;
+}
+export interface PluginSkip {
+    id: string;
+    reason: string;
+}
+export interface PluginWriteResult {
+    profile: string;
+    patchPath: string;
+    changed: boolean;
+    dryRun: boolean;
+    changes: PluginChange[];
+    skipped: PluginSkip[];
+}
+export declare function resolvePluginProfile(target: PluginSetupTarget): Promise<string>;
+/** Secret-bearing key names; handles/env names/paths/ttls are not secrets. */
+export declare function isSecretConfigKey(name: string): boolean;
+/** Map `work-items`, `assistant-work-items`, `@dsh-enhanced/assistant-work-items` or the row id to an installed row id. */
+export declare function resolvePluginId(name: string, installed: Iterable<string>): string | undefined;
+/**
+ * Convert a CLI string to the type of the current effective value. Unknown keys
+ * need `force`; documented optional keys are typed from a small table.
+ */
+export declare function coerceConfigValue(id: string, key: string, raw: string, current: unknown, force?: boolean): unknown;
+export declare function listProfilePlugins(target: PluginSetupTarget, options?: PluginSetupOptions): Promise<{
+    profile: string;
+    patchPath: string;
+    plugins: ProfilePluginSummary[];
+}>;
+/** Effective config of one plugin with secret-like values redacted. */
+export declare function showProfilePlugin(target: PluginSetupTarget & {
+    plugin: string;
+}, options?: PluginSetupOptions): Promise<{
+    profile: string;
+    summary: ProfilePluginSummary;
+    config: string;
+}>;
+/**
+ * Enable or disable one plugin: flips the loader row gate and, when the plugin
+ * has a top-level `enabled` config gate, that gate too.
+ */
+export declare function setPluginEnabled(target: PluginSetupTarget & {
+    plugin: string;
+    enabled: boolean;
+}, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+/** Set one config key (dotted path) after validating it against the effective value type. */
+export declare function setPluginConfigValue(target: PluginSetupTarget & {
+    plugin: string;
+    key: string;
+    value: string;
+    force?: boolean;
+}, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+/** Remove one config key from the profile override so the plugin default applies. */
+export declare function unsetPluginConfigValue(target: PluginSetupTarget & {
+    plugin: string;
+    key: string;
+}, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+export interface PresetItem {
+    id: string;
+    purpose: string;
+    set: ReadonlyArray<readonly [key: string, value: boolean | string]>;
+}
+/**
+ * The `recommended` preset deliberately turns on opt-in features that stay off
+ * by default. It edits only plugins that are installed and loaded, never loads
+ * a disabled plugin, never touches credentials, Policy, owner routes or sealed
+ * plugin state, and leaves the automations scheduler to the RSI/supervised setup.
+ */
+export declare const recommendedPluginPreset: readonly PresetItem[];
+export declare const pluginPresets: ReadonlyMap<string, readonly PresetItem[]>;
+/**
+ * Apply a named plugin preset (default `recommended`) to one profile in a
+ * single verified write. Intended for onboarding flows:
+ *
+ * ```ts
+ * import { applyRecommendedPluginPreset } from '@dsh-enhanced/assistant-policy/plugin-setup'
+ * const result = await applyRecommendedPluginPreset({ dshHome, profile: 'web' })
+ * ```
+ *
+ * Idempotent: re-running reports no changes.
+ */
+export declare function applyPluginPreset(target: PluginSetupTarget & {
+    preset?: string;
+}, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+/** Onboarding entry point: apply the `recommended` plugin preset. */
+export declare function applyRecommendedPluginPreset(target: PluginSetupTarget, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+export type PluginSetupCommand = 'list' | 'show' | 'enable' | 'disable' | 'set' | 'unset' | 'preset' | 'guided';
+export interface PluginSetupArgs {
+    command: PluginSetupCommand;
+    positionals: string[];
+    dshHome: string;
+    profile?: string;
+    force: boolean;
+    dryRun: boolean;
+    yes: boolean;
+    json: boolean;
+    help: boolean;
+}
+export declare function parsePluginSetupArgs(argv: readonly string[]): PluginSetupArgs;
+export declare function pluginSetupUsage(): string;
+export interface PluginSetupIo {
+    write(text: string): void;
+    isTTY: boolean;
+    /** Ask one question; resolves to the trimmed answer. */
+    ask?(question: string): Promise<string>;
+}
+export declare function runPluginSetup(argv?: string[], io?: PluginSetupIo, options?: Omit<PluginSetupOptions, 'dryRun'>): Promise<void>;
+//# sourceMappingURL=plugin-setup.d.ts.map

package/lib/plugin-setup.d.ts.map

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