@aiwg/cli 2026.10.11 → 2026.10.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (174) hide show
  1. package/agentic/code/providers/model-catalog.v1.json +62 -12
  2. package/agentic/code/providers/pi/aiwg-bridge.ts +44 -1
  3. package/dist/src/artifacts/binding-target-identity.js +51 -0
  4. package/dist/src/artifacts/checksum-manifest.js +12 -0
  5. package/dist/src/artifacts/index-builder.js +11 -13
  6. package/dist/src/artifacts/query-engine.js +5 -11
  7. package/dist/src/cli/handlers/doctor-help.js +32 -0
  8. package/dist/src/cli/handlers/gates.js +19 -18
  9. package/dist/src/cli/handlers/models-help.js +7 -1
  10. package/dist/src/cli/handlers/models.js +3 -3
  11. package/dist/src/cli/handlers/script-runner.js +8 -5
  12. package/dist/src/cli/handlers/sessions-intake.js +104 -0
  13. package/dist/src/cli/handlers/sessions-tail.js +172 -0
  14. package/dist/src/cli/handlers/sessions.js +90 -17
  15. package/dist/src/cli/handlers/skill-lint.js +10 -3
  16. package/dist/src/cli/handlers/steward-format.js +100 -0
  17. package/dist/src/cli/handlers/steward-models.js +167 -0
  18. package/dist/src/cli/handlers/steward.js +14 -248
  19. package/dist/src/cli/handlers/use-bundle-counts.js +87 -0
  20. package/dist/src/cli/handlers/use-skill-assets.js +207 -0
  21. package/dist/src/cli/handlers/use.js +35 -216
  22. package/dist/src/cli/handlers/utilities.js +1 -24
  23. package/dist/src/config/aiwg-config.js +7 -0
  24. package/dist/src/config/authorization-cli.js +97 -0
  25. package/dist/src/config/cli-help.js +1 -0
  26. package/dist/src/config/cli.js +10 -1
  27. package/dist/src/decision/context-pruning-common.js +41 -0
  28. package/dist/src/decision/context-pruning-evaluation.js +366 -0
  29. package/dist/src/decision/context-pruning-pilot.js +431 -0
  30. package/dist/src/decision/context-pruning-types.js +19 -0
  31. package/dist/src/decision/context-pruning.js +5 -846
  32. package/dist/src/decision/ensemble/contract.js +17 -26
  33. package/dist/src/decision/ensemble-study/artifacts.js +5 -0
  34. package/dist/src/decision/ensemble-study/score.js +4 -3
  35. package/dist/src/decision/feature-export.js +3 -9
  36. package/dist/src/decision/heldout/collector.js +2 -2
  37. package/dist/src/decision/issue-triage/runtime.js +3 -9
  38. package/dist/src/decision/qualification/gates.js +2 -1
  39. package/dist/src/decision/qualification/release.js +6 -64
  40. package/dist/src/decision/routing/report.js +2 -0
  41. package/dist/src/decision/sdlc-screening.js +3 -5
  42. package/dist/src/decision/sensitivity/comparative.js +5 -3
  43. package/dist/src/extensions/manifest.js +8 -1
  44. package/dist/src/extensions/project-local-doctor.js +78 -2
  45. package/dist/src/extensions/validation.js +10 -11
  46. package/dist/src/gates/driver.js +6 -77
  47. package/dist/src/gates/evaluate.js +6 -23
  48. package/dist/src/gates/floors.js +4 -4
  49. package/dist/src/gates/index.js +3 -3
  50. package/dist/src/gates/lattice.js +26 -0
  51. package/dist/src/gates/registry.js +2 -1
  52. package/dist/src/gates/report.js +19 -7
  53. package/dist/src/gates/upstream-ceiling.js +111 -0
  54. package/dist/src/issues/audit-cli.js +120 -0
  55. package/dist/src/issues/audit-contract.js +64 -0
  56. package/dist/src/issues/audit-local.js +82 -0
  57. package/dist/src/issues/audit.js +220 -0
  58. package/dist/src/lint/rule-activation.js +15 -1
  59. package/dist/src/mission-protocol/canonical-codecs.js +270 -0
  60. package/dist/src/mission-protocol/codecs.js +22 -550
  61. package/dist/src/mission-protocol/health-trace-codecs.js +281 -0
  62. package/dist/src/mission-protocol/health-trace-types.js +43 -0
  63. package/dist/src/mission-protocol/types.js +2 -42
  64. package/dist/src/mission-protocol/worker-contract-json.js +10 -0
  65. package/dist/src/mission-protocol/worker-review-gate.js +100 -0
  66. package/dist/src/mission-protocol/worker-review-types.js +2 -0
  67. package/dist/src/models/catalog-policy.js +280 -0
  68. package/dist/src/models/index.js +1 -1
  69. package/dist/src/models/model-catalog.v1.json +62 -12
  70. package/dist/src/models/policy-resources.js +28 -0
  71. package/dist/src/models/provider-models.js +5 -8
  72. package/dist/src/models/provider-policy.js +10 -546
  73. package/dist/src/models/resolver.js +26 -8
  74. package/dist/src/models/router.js +15 -2
  75. package/dist/src/models/tiers.js +13 -0
  76. package/dist/src/models/types.js +0 -6
  77. package/dist/src/models/worker-ceilings.js +59 -0
  78. package/dist/src/models/worker-invocation-policy.js +243 -0
  79. package/dist/src/models/worker-plan.js +16 -20
  80. package/dist/src/models/worker-review-lineage.js +55 -0
  81. package/dist/src/models/worker-selection-policy.js +1 -1
  82. package/dist/src/models/wrapper-definitions.js +14 -0
  83. package/dist/src/models/wrapper-deployment.js +48 -25
  84. package/dist/src/models/wrapper-enforcement.js +72 -0
  85. package/dist/src/models/wrapper-route.js +6 -3
  86. package/dist/src/policy/authorization.js +1 -0
  87. package/dist/src/policy/hitl-check.js +80 -0
  88. package/dist/src/policy/hitl-config.js +63 -0
  89. package/dist/src/policy/hitl-receipt.js +57 -0
  90. package/dist/src/policy/hitl-types.js +4 -0
  91. package/dist/src/policy/hitl-validation.js +39 -0
  92. package/dist/src/policy/hitl.js +117 -0
  93. package/dist/src/rules/activation.d.mts +3 -1
  94. package/dist/src/rules/activation.mjs +23 -2
  95. package/dist/src/rules/gate-coverage.js +51 -0
  96. package/dist/src/rules/gate-references.js +16 -0
  97. package/dist/src/rules/rule-frontmatter.schema.json +7 -1
  98. package/dist/src/serve/worker-command-request.js +21 -4
  99. package/dist/src/serve/worker-invocation-preparation.js +3 -1
  100. package/dist/src/serve/worker-invocation.js +21 -10
  101. package/dist/src/sessions/adapters/deepseek-harness.js +1 -0
  102. package/dist/src/sessions/adapters/grok-build-native.js +269 -0
  103. package/dist/src/sessions/adapters/grok-build.js +57 -15
  104. package/dist/src/sessions/adapters/hermes-state-db.js +252 -0
  105. package/dist/src/sessions/adapters/hermes.js +42 -3
  106. package/dist/src/sessions/adapters/warp.js +1 -1
  107. package/dist/src/sessions/batch-import.js +10 -0
  108. package/dist/src/sessions/contracts.js +1 -1
  109. package/dist/src/sessions/discovery-capability.js +38 -0
  110. package/dist/src/sessions/importer.js +8 -251
  111. package/dist/src/sessions/index.js +4 -0
  112. package/dist/src/sessions/intake-dir.js +71 -0
  113. package/dist/src/sessions/normalization.js +251 -0
  114. package/dist/src/sessions/tail.js +91 -0
  115. package/dist/src/sessions/workspace-discovery.js +83 -7
  116. package/dist/src/skills/adapters/local.js +32 -9
  117. package/dist/src/skills/agent-skill-sidecar.js +28 -0
  118. package/dist/src/skills/agent-skills.js +6 -23
  119. package/dist/src/skills/claude-surface-projection.js +25 -0
  120. package/dist/src/skills/cli-display.js +33 -0
  121. package/dist/src/skills/cli.js +2 -26
  122. package/dist/src/skills/collision-discovery.js +84 -0
  123. package/dist/src/skills/deployer.js +26 -361
  124. package/dist/src/skills/deployment-ownership.js +74 -0
  125. package/dist/src/skills/deployment-policy.js +114 -0
  126. package/dist/src/skills/deployment-projection.js +152 -0
  127. package/dist/src/skills/deployment-types.js +20 -0
  128. package/dist/src/skills/doctor.js +2 -2
  129. package/dist/src/skills/exporter.js +8 -31
  130. package/dist/src/skills/importer.js +4 -26
  131. package/dist/src/skills/provider-extensions.js +41 -0
  132. package/dist/src/skills/registry.js +22 -7
  133. package/dist/src/skills/run.js +6 -0
  134. package/dist/src/skills/types.js +0 -8
  135. package/dist/src/skills/validator-resources.js +68 -0
  136. package/dist/src/skills/validator.js +6 -55
  137. package/dist/src/smiths/context-pipeline/parallelism-section.js +7 -3
  138. package/dist/src/storage/cli-migrate-options.js +125 -0
  139. package/dist/src/storage/cli-migrate.js +111 -0
  140. package/dist/src/storage/cli.js +4 -279
  141. package/dist/src/storage/migration-adapter.js +79 -0
  142. package/dist/src/storage/migration-copy.js +108 -0
  143. package/dist/src/storage/migration-protocol.js +14 -197
  144. package/dist/src/storage/migration-records.js +186 -0
  145. package/dist/src/storage/migration-types.js +12 -0
  146. package/dist/src/tracker/forge-http.js +2 -1
  147. package/dist/src/tracker/issue-pages.js +110 -0
  148. package/package.json +3 -1
  149. package/schemas/mission-v1.schema.json +335 -0
  150. package/schemas/models/model-catalog.v1.schema.json +19 -1
  151. package/schemas/models/model-config-compatibility.v1.schema.json +3 -2
  152. package/schemas/models/model-policy.v1.schema.json +1 -1
  153. package/tools/agents/providers/antigravity.mjs +3 -5
  154. package/tools/agents/providers/base.mjs +3 -3
  155. package/tools/agents/providers/claude.mjs +3 -5
  156. package/tools/agents/providers/codex.mjs +3 -5
  157. package/tools/agents/providers/copilot.mjs +3 -5
  158. package/tools/agents/providers/cursor.mjs +3 -5
  159. package/tools/agents/providers/factory.mjs +3 -5
  160. package/tools/agents/providers/grok-build.mjs +9 -7
  161. package/tools/agents/providers/model-wrapper.mjs +86 -0
  162. package/tools/agents/providers/omp.mjs +3 -1
  163. package/tools/agents/providers/openclaw.mjs +3 -5
  164. package/tools/agents/providers/opencode.mjs +3 -5
  165. package/tools/agents/providers/provider-paths-staging.mjs +44 -0
  166. package/tools/agents/providers/rule-binding-targets.mjs +146 -0
  167. package/tools/agents/providers/rule-delivery.mjs +9 -128
  168. package/tools/agents/providers/warp.mjs +3 -5
  169. package/tools/agents/providers/windsurf.mjs +3 -5
  170. package/tools/plugin/package-plugins.mjs +2 -2
  171. package/tools/skills/codex-skill-transform.mjs +232 -0
  172. package/tools/skills/deploy-skills-codex.mjs +8 -249
  173. package/tools/warp/warp-content.mjs +548 -0
  174. package/vscode-extension/schemas/aiwg.config.v1.json +177 -0
@@ -7,343 +7,15 @@
7
7
  * @implements #1879
8
8
  */
9
9
  import fs from 'node:fs';
10
- import os from 'node:os';
11
10
  import path from 'node:path';
12
11
  import { randomUUID } from 'node:crypto';
13
- import { stringify } from 'yaml';
14
- import { getProviderDefinition, normalizeProviderDefinitionId, } from '../providers/provider-definitions.js';
15
- import { AGENT_SKILLS_SIDECAR_SCHEMA, AIWG_SKILL_CONTROL_FIELDS, createAgentSkillSidecar, projectStrictAgentSkill, } from './agent-skills.js';
16
12
  import { getImportedAgentSkill } from './importer.js';
17
- import { validateAgentSkillContent } from './validator.js';
18
- import { resolveHermesHomePath } from '../providers/hermes-home.js';
19
- import { museXdgSkillsDirRemediation, resolveMuseXdgSkillsDir, } from '../providers/muse-paths.js';
20
- import { GROKBOT_SKILLS_DIR_ENV, grokbotMissingRootRemediation, resolveGrokbotSkillsDir, } from '../providers/grokbot-paths.js';
21
- export const AGENT_SKILL_MANAGED_MARKER = '.aiwg-managed';
22
- export const AGENT_SKILL_DEPLOYMENT_SIDECAR = '.aiwg-agent-skill.json';
23
- const MARKER_CONTENT = 'aiwg-agent-skill-v1\n';
24
- const STANDARD_FIELDS = [
25
- 'name',
26
- 'description',
27
- 'license',
28
- 'compatibility',
29
- 'metadata',
30
- 'allowed-tools',
31
- ];
32
- const AIWG_FIELDS = new Set(AIWG_SKILL_CONTROL_FIELDS);
33
- export class AgentSkillDeploymentError extends Error {
34
- code;
35
- constructor(code, message) {
36
- super(message);
37
- this.code = code;
38
- this.name = 'AgentSkillDeploymentError';
39
- }
40
- }
41
- function fail(code, message) {
42
- throw new AgentSkillDeploymentError(code, message);
43
- }
44
- function assertPortableName(name) {
45
- if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || name.length > 64) {
46
- fail('AS_DEPLOY_NAME', 'Agent Skill name must be 1-64 lowercase ASCII letters, numbers, or single hyphens');
47
- }
48
- }
49
- function resolvedHome(options) {
50
- return path.resolve(options.homeDir ?? os.homedir());
51
- }
52
- function resolvePolicy(target, options) {
53
- const provider = normalizeProviderDefinitionId(target);
54
- if (!provider) {
55
- fail('AS_DEPLOY_PROVIDER', `unknown Agent Skills target "${target}"`);
56
- }
57
- const definition = getProviderDefinition(provider);
58
- if (!definition) {
59
- fail('AS_DEPLOY_PROVIDER', `provider definition is unavailable for "${provider}"`);
60
- }
61
- const namespace = definition.skillNamespace;
62
- const reasons = [];
63
- const warnings = [];
64
- let root = namespace.pathType === 'home-dir'
65
- ? path.join(resolvedHome(options), namespace.skillsBaseDir)
66
- : path.join(path.resolve(options.projectDir), namespace.skillsBaseDir);
67
- let status = 'native';
68
- let supported = true;
69
- let appendToDescription;
70
- let maxDescriptionLength;
71
- switch (provider) {
72
- case 'codex':
73
- root = path.join(path.resolve(options.projectDir), '.agents', 'skills');
74
- status = 'projected';
75
- maxDescriptionLength = namespace.maxDescriptionLength;
76
- reasons.push('uses the project .agents/skills compatibility surface without the legacy 100/500 truncation transform');
77
- break;
78
- case 'factory':
79
- status = 'projected';
80
- appendToDescription = namespace.appendToDescription;
81
- reasons.push('applies the Factory description guidance before strict validation');
82
- break;
83
- case 'grokbot': {
84
- // Fail closed: never invent ~/grokbot-skills or ~/.grokbot.
85
- const configured = resolveGrokbotSkillsDir(process.env);
86
- if (!configured) {
87
- root = '';
88
- status = 'unsupported';
89
- supported = false;
90
- reasons.push(grokbotMissingRootRemediation(process.env));
91
- warnings.push(`Agent Skills deploy for grokbot requires absolute ${GROKBOT_SKILLS_DIR_ENV}; no filesystem root was invented`);
92
- }
93
- else {
94
- root = configured;
95
- reasons.push(`uses the operator-configured ${GROKBOT_SKILLS_DIR_ENV} skills root with strict managed ownership markers`);
96
- }
97
- break;
98
- }
99
- case 'hermes':
100
- if (options.homeDir === undefined) {
101
- root = resolveHermesHomePath('skills');
102
- }
103
- reasons.push('uses the active HERMES_HOME skills surface with strict managed ownership markers');
104
- break;
105
- case 'muse': {
106
- // ADR scope rule 1: the default projection is the project
107
- // <repo>/.agents/skills surface shared with antigravity, codex, and
108
- // deepseek-harness. Muse reads both that root and its XDG user root,
109
- // so writing the user root by default would list a skill twice.
110
- // #234: an explicit user scope resolves the documented XDG root at
111
- // deploy time — never ~/.muse — and bad XDG metadata fails closed.
112
- if (options.scope === 'user') {
113
- const home = resolvedHome(options);
114
- const configured = resolveMuseXdgSkillsDir(process.env, home);
115
- if (!configured) {
116
- root = '';
117
- status = 'unsupported';
118
- supported = false;
119
- reasons.push(museXdgSkillsDirRemediation(process.env, home));
120
- warnings.push('Agent Skills deploy for muse requires a valid absolute XDG_CONFIG_HOME; no filesystem root was invented');
121
- }
122
- else {
123
- root = configured;
124
- reasons.push('uses the Muse XDG user skills root ($XDG_CONFIG_HOME/muse/skills, default ~/.config/muse/skills) with strict managed ownership markers');
125
- }
126
- }
127
- else {
128
- reasons.push('uses the project .agents/skills surface shared with antigravity, codex, and deepseek-harness');
129
- }
130
- break;
131
- }
132
- case 'openhuman':
133
- status = 'projected';
134
- reasons.push('uses the verified global one-level ~/.openhuman/skills layout');
135
- break;
136
- case 'windsurf':
137
- status = 'projected';
138
- reasons.push('uses one skill bundle directly below the one-level .windsurf/skills surface');
139
- break;
140
- default:
141
- reasons.push('provider exposes a native recursive Agent Skills bundle surface');
142
- }
143
- return {
144
- provider,
145
- root,
146
- status,
147
- supported,
148
- reasons,
149
- warnings,
150
- appendToDescription,
151
- maxDescriptionLength,
152
- };
153
- }
154
- function assertSafeSourceEntry(sourceRoot, absolutePath, relativePath) {
155
- const stat = fs.lstatSync(absolutePath);
156
- if (stat.isSymbolicLink()) {
157
- fail('AS_DEPLOY_SOURCE_SYMLINK', `managed source contains a symlink: ${relativePath}`);
158
- }
159
- if (!stat.isDirectory() && !stat.isFile()) {
160
- fail('AS_DEPLOY_SOURCE_SPECIAL_FILE', `managed source contains a non-regular entry: ${relativePath}`);
161
- }
162
- const real = fs.realpathSync.native(absolutePath);
163
- const relativeReal = path.relative(fs.realpathSync.native(sourceRoot), real);
164
- if (relativeReal.startsWith('..') || path.isAbsolute(relativeReal)) {
165
- fail('AS_DEPLOY_SOURCE_ESCAPE', `managed source entry escapes its root: ${relativePath}`);
166
- }
167
- return stat;
168
- }
169
- function collectSourceEntries(sourceRoot) {
170
- const entries = [];
171
- const walk = (current, prefix) => {
172
- for (const entry of fs.readdirSync(current, { withFileTypes: true })
173
- .sort((left, right) => left.name.localeCompare(right.name))) {
174
- const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
175
- if (relativePath === AGENT_SKILL_MANAGED_MARKER
176
- || relativePath === AGENT_SKILL_DEPLOYMENT_SIDECAR) {
177
- fail('AS_DEPLOY_RESERVED_PATH', `managed source uses reserved deployment path "${relativePath}"`);
178
- }
179
- const absolutePath = path.join(current, entry.name);
180
- const stat = assertSafeSourceEntry(sourceRoot, absolutePath, relativePath);
181
- if (stat.isDirectory()) {
182
- entries.push({ kind: 'directory', relativePath });
183
- walk(absolutePath, relativePath);
184
- }
185
- else {
186
- entries.push({
187
- kind: 'file',
188
- relativePath,
189
- bytes: fs.readFileSync(absolutePath),
190
- });
191
- }
192
- }
193
- };
194
- walk(sourceRoot, '');
195
- return entries;
196
- }
197
- function projectionDocument(record) {
198
- const sourceEntries = collectSourceEntries(record.managedLocation);
199
- const skillFile = sourceEntries.find((entry) => (entry.kind === 'file' && entry.relativePath === 'SKILL.md'));
200
- if (!skillFile) {
201
- fail('AS_DEPLOY_SKILL_MISSING', 'managed source does not contain SKILL.md');
202
- }
203
- const content = new TextDecoder('utf-8', { fatal: true }).decode(skillFile.bytes);
204
- const validation = validateAgentSkillContent(content, {
205
- profile: record.validationProfile,
206
- file: path.join(record.managedLocation, 'SKILL.md'),
207
- directoryName: record.name,
208
- skillRoot: record.managedLocation,
209
- checkResources: true,
210
- });
211
- if (!validation.valid || !validation.frontmatter) {
212
- fail('AS_DEPLOY_SOURCE_INVALID', `managed source for "${record.name}" no longer passes ${record.validationProfile} validation`);
213
- }
214
- const standard = {};
215
- for (const key of STANDARD_FIELDS) {
216
- const value = validation.frontmatter[key];
217
- if (value !== undefined) {
218
- Object.assign(standard, { [key]: structuredClone(value) });
219
- }
220
- }
221
- const aiwg = {};
222
- for (const [key, value] of Object.entries(validation.frontmatter)) {
223
- if (AIWG_FIELDS.has(key)) {
224
- aiwg[key] = structuredClone(value);
225
- }
226
- }
227
- return {
228
- document: {
229
- standard: standard,
230
- body: validation.body,
231
- resources: [],
232
- aiwg,
233
- unknownFields: [],
234
- },
235
- sourceEntries,
236
- };
237
- }
238
- function strictSkillBytes(record, policy, document) {
239
- const metadata = projectStrictAgentSkill(document);
240
- if (policy.appendToDescription) {
241
- const suffix = policy.appendToDescription;
242
- if (!metadata.description.endsWith(suffix)) {
243
- metadata.description = `${metadata.description.trimEnd()} ${suffix}`;
244
- }
245
- }
246
- if (policy.maxDescriptionLength !== undefined
247
- && metadata.description.length > policy.maxDescriptionLength) {
248
- policy.status = 'degraded';
249
- policy.supported = false;
250
- policy.reasons.push(`description length ${metadata.description.length} exceeds the provider limit ${policy.maxDescriptionLength}; no truncation was applied`);
251
- return undefined;
252
- }
253
- const frontmatter = stringify(metadata, {
254
- lineWidth: 0,
255
- sortMapEntries: false,
256
- }).trimEnd();
257
- const content = `---\n${frontmatter}\n---\n${document.body}`;
258
- const validation = validateAgentSkillContent(content, {
259
- profile: 'strict',
260
- file: 'SKILL.md',
261
- directoryName: record.name,
262
- });
263
- if (!validation.valid) {
264
- policy.status = 'degraded';
265
- policy.supported = false;
266
- policy.reasons.push(`provider projection failed strict validation: ${validation.diagnostics
267
- .filter((item) => item.severity === 'error')
268
- .map((item) => item.code)
269
- .join(', ')}`);
270
- return undefined;
271
- }
272
- return Buffer.from(content, 'utf8');
273
- }
274
- function sidecarBytes(record, policy, document) {
275
- const portableSidecar = createAgentSkillSidecar(document, {
276
- sourceKind: record.source.kind,
277
- locator: record.source.locator,
278
- ...(record.source.kind === 'git'
279
- ? {
280
- requestedRevision: record.source.requestedRevision,
281
- resolvedRevision: record.source.resolvedRevision,
282
- }
283
- : {}),
284
- sourceDigest: record.digest,
285
- importedAt: record.importedAt,
286
- aiwgVersion: record.aiwgVersion,
287
- }, record.validationProfile, record.trust);
288
- return Buffer.from(`${JSON.stringify({
289
- schemaVersion: 1,
290
- kind: 'aiwg-managed-agent-skill-projection',
291
- name: record.name,
292
- provider: policy.provider,
293
- projectionStatus: policy.status,
294
- sourceDigest: record.digest,
295
- reasons: policy.reasons,
296
- warnings: policy.warnings,
297
- portable: portableSidecar,
298
- }, null, 2)}\n`, 'utf8');
299
- }
300
- function readDeploymentSidecar(targetPath, expectedName, expectedProvider) {
301
- try {
302
- const sidecarPath = path.join(targetPath, AGENT_SKILL_DEPLOYMENT_SIDECAR);
303
- const stat = fs.lstatSync(sidecarPath);
304
- if (!stat.isFile() || stat.isSymbolicLink())
305
- return undefined;
306
- const value = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
307
- if (value.schemaVersion !== 1
308
- || value.kind !== 'aiwg-managed-agent-skill-projection'
309
- || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value.name)
310
- || !normalizeProviderDefinitionId(value.provider)
311
- || !/^[0-9a-f]{64}$/.test(value.sourceDigest)
312
- || !['native', 'projected', 'degraded', 'unsupported'].includes(value.projectionStatus)
313
- || !Array.isArray(value.reasons)
314
- || !value.reasons.every((item) => typeof item === 'string')
315
- || !Array.isArray(value.warnings)
316
- || !value.warnings.every((item) => typeof item === 'string')
317
- || value.portable?.$schema !== AGENT_SKILLS_SIDECAR_SCHEMA
318
- || value.portable.schemaVersion !== 1
319
- || typeof value.portable.aiwg !== 'object'
320
- || value.portable.aiwg === null
321
- || Array.isArray(value.portable.aiwg)
322
- || value.portable.provenance?.sourceDigest !== value.sourceDigest
323
- || !['strict', 'compatible', 'discovery'].includes(value.portable.validationProfile)
324
- || !['untrusted', 'trusted', 'revoked'].includes(value.portable.trust?.state)
325
- || !['inactive', 'active', 'blocked'].includes(value.portable.trust?.activation)
326
- || (expectedName !== undefined && value.name !== expectedName)
327
- || (expectedProvider !== undefined && value.provider !== expectedProvider)
328
- || path.basename(targetPath) !== value.name) {
329
- return undefined;
330
- }
331
- return value;
332
- }
333
- catch {
334
- return undefined;
335
- }
336
- }
337
- /**
338
- * Codex, Antigravity, DeepSeek Harness, and Muse intentionally consume the
339
- * same portable project skill surface (<repo>/.agents/skills). A projection
340
- * written for any member is managed ownership for the others when the
341
- * desired payload is otherwise byte-identical.
342
- */
343
- function providersShareProjectionSurface(actual, expected) {
344
- const shared = new Set(['antigravity', 'codex', 'deepseek-harness', 'muse']);
345
- return actual === expected || (shared.has(actual) && shared.has(expected));
346
- }
13
+ import { higherLocalSkillOwner, skillCollisionDiagnostic } from './collision-discovery.js';
14
+ import { isManagedTarget, readDeploymentSidecar, providersShareProjectionSurface } from './deployment-ownership.js';
15
+ import { resolvePolicy } from './deployment-policy.js';
16
+ import { projectionDocument, providerSkillBytes, sidecarBytes } from './deployment-projection.js';
17
+ import { AGENT_SKILL_MANAGED_MARKER, AGENT_SKILL_DEPLOYMENT_SIDECAR, MARKER_CONTENT, assertPortableName, fail, } from './deployment-types.js';
18
+ export { AGENT_SKILL_MANAGED_MARKER, AGENT_SKILL_DEPLOYMENT_SIDECAR, AgentSkillDeploymentError, } from './deployment-types.js';
347
19
  function buildProjectionPlan(record, options) {
348
20
  const policy = resolvePolicy(options.target, options);
349
21
  const targetPath = path.join(policy.root, record.name);
@@ -355,8 +27,17 @@ function buildProjectionPlan(record, options) {
355
27
  desiredEntries: [],
356
28
  };
357
29
  }
30
+ const collision = higherLocalSkillOwner(record.name, 'imported', options);
31
+ if (collision?.origin) {
32
+ const diagnostic = skillCollisionDiagnostic(record.name, collision.origin, 'imported', collision.path ?? '');
33
+ policy.status = 'degraded';
34
+ policy.reasons.push(diagnostic.message);
35
+ policy.warnings.push(`Existing ${collision.origin}-owned files were not modified: ${collision.path}`);
36
+ return { blocked: true, policy, targetPath, sourceDigest: record.digest, desiredEntries: [] };
37
+ }
358
38
  const { document, sourceEntries } = projectionDocument(record);
359
- const skillBytes = strictSkillBytes(record, policy, document);
39
+ const original = sourceEntries.find((entry) => (entry.kind === 'file' && entry.relativePath === 'SKILL.md'));
40
+ const skillBytes = providerSkillBytes(record, policy, document, original?.bytes);
360
41
  if (!skillBytes) {
361
42
  return {
362
43
  policy,
@@ -388,26 +69,6 @@ function buildProjectionPlan(record, options) {
388
69
  desiredEntries,
389
70
  };
390
71
  }
391
- function isManagedTarget(targetPath, expectedName, expectedProvider) {
392
- if (!fs.existsSync(targetPath))
393
- return false;
394
- try {
395
- const targetStat = fs.lstatSync(targetPath);
396
- const marker = path.join(targetPath, AGENT_SKILL_MANAGED_MARKER);
397
- const sidecar = readDeploymentSidecar(targetPath, expectedName);
398
- return (targetStat.isDirectory()
399
- && !targetStat.isSymbolicLink()
400
- && fs.lstatSync(marker).isFile()
401
- && !fs.lstatSync(marker).isSymbolicLink()
402
- && fs.readFileSync(marker, 'utf8') === MARKER_CONTENT
403
- && sidecar !== undefined
404
- && (expectedProvider === undefined
405
- || providersShareProjectionSurface(sidecar.provider, expectedProvider)));
406
- }
407
- catch {
408
- return false;
409
- }
410
- }
411
72
  function targetMatches(targetPath, desired, name, provider) {
412
73
  if (!isManagedTarget(targetPath, name, provider))
413
74
  return false;
@@ -476,6 +137,9 @@ function promoteAtomically(name, plan) {
476
137
  const existed = fs.existsSync(plan.targetPath);
477
138
  try {
478
139
  writeDesiredTree(staging, plan.desiredEntries);
140
+ if (!existed && fs.existsSync(plan.targetPath)) {
141
+ fail('AS_DEPLOY_COLLISION_RACE', 'project/user-owned target appeared before imported-owned skill promotion');
142
+ }
479
143
  if (existed) {
480
144
  if (!isManagedTarget(plan.targetPath, name, plan.policy.provider)) {
481
145
  fail('AS_DEPLOY_COLLISION_RACE', 'deployment target ownership changed before atomic promotion');
@@ -486,11 +150,11 @@ function promoteAtomically(name, plan) {
486
150
  fs.renameSync(staging, plan.targetPath);
487
151
  }
488
152
  catch (error) {
489
- if (fs.existsSync(plan.targetPath)) {
490
- fs.rmSync(plan.targetPath, { recursive: true, force: true });
491
- }
492
- if (fs.existsSync(backup))
153
+ // A failed rename did not install our tree. A newly appeared target is
154
+ // operator-owned; retain it and the backup rather than deleting either.
155
+ if (fs.existsSync(backup) && !fs.existsSync(plan.targetPath)) {
493
156
  fs.renameSync(backup, plan.targetPath);
157
+ }
494
158
  throw error;
495
159
  }
496
160
  if (fs.existsSync(backup)) {
@@ -548,13 +212,13 @@ export function deployImportedAgentSkill(name, options) {
548
212
  const record = requireDeployableImport(name, projectDir);
549
213
  const plan = buildProjectionPlan(record, { ...options, projectDir });
550
214
  const dryRun = options.dryRun ?? false;
551
- if (!plan.policy.supported) {
215
+ if (!plan.policy.supported || plan.blocked) {
552
216
  return result('deploy', 'blocked', dryRun, name, plan);
553
217
  }
554
218
  if (fs.existsSync(plan.targetPath)
555
219
  && !isManagedTarget(plan.targetPath, name, plan.policy.provider)) {
556
220
  plan.policy.status = 'degraded';
557
- plan.policy.reasons.push('target collision is not owned by AIWG');
221
+ plan.policy.reasons.push('target collision is not owned by AIWG: project/user-owned target blocks imported-owned skill');
558
222
  plan.policy.warnings.push('the existing user-owned target was not modified');
559
223
  return result('deploy', 'blocked', dryRun, name, plan);
560
224
  }
@@ -614,6 +278,7 @@ export function inspectImportedAgentSkillProjection(name, options) {
614
278
  exists,
615
279
  managed,
616
280
  matches: (plan.policy.supported
281
+ && !plan.blocked
617
282
  && managed
618
283
  && targetMatches(plan.targetPath, plan.desiredEntries, name, plan.policy.provider)),
619
284
  reasons: [...plan.policy.reasons],
@@ -0,0 +1,74 @@
1
+ // Verify managed projection ownership before discovery or mutation.
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { normalizeProviderDefinitionId } from '../providers/provider-definitions.js';
5
+ import { AGENT_SKILLS_SIDECAR_SCHEMA } from './agent-skills.js';
6
+ import { AGENT_SKILL_DEPLOYMENT_SIDECAR, AGENT_SKILL_MANAGED_MARKER, MARKER_CONTENT, } from './deployment-types.js';
7
+ export function readDeploymentSidecar(targetPath, expectedName, expectedProvider) {
8
+ try {
9
+ const sidecarPath = path.join(targetPath, AGENT_SKILL_DEPLOYMENT_SIDECAR);
10
+ const stat = fs.lstatSync(sidecarPath);
11
+ if (!stat.isFile() || stat.isSymbolicLink())
12
+ return undefined;
13
+ const value = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
14
+ if (value.schemaVersion !== 1
15
+ || value.kind !== 'aiwg-managed-agent-skill-projection'
16
+ || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value.name)
17
+ || !normalizeProviderDefinitionId(value.provider)
18
+ || !/^[0-9a-f]{64}$/.test(value.sourceDigest)
19
+ || !['native', 'projected', 'degraded', 'unsupported'].includes(value.projectionStatus)
20
+ || !Array.isArray(value.reasons)
21
+ || !value.reasons.every((item) => typeof item === 'string')
22
+ || !Array.isArray(value.warnings)
23
+ || !value.warnings.every((item) => typeof item === 'string')
24
+ || value.portable?.$schema !== AGENT_SKILLS_SIDECAR_SCHEMA
25
+ || value.portable.schemaVersion !== 1
26
+ || typeof value.portable.aiwg !== 'object'
27
+ || value.portable.aiwg === null
28
+ || Array.isArray(value.portable.aiwg)
29
+ || value.portable.provenance?.sourceDigest !== value.sourceDigest
30
+ || !['strict', 'compatible', 'discovery'].includes(value.portable.validationProfile)
31
+ || !['untrusted', 'trusted', 'revoked'].includes(value.portable.trust?.state)
32
+ || !['inactive', 'active', 'blocked'].includes(value.portable.trust?.activation)
33
+ || (expectedName !== undefined && value.name !== expectedName)
34
+ || (expectedProvider !== undefined && value.provider !== expectedProvider)
35
+ || path.basename(targetPath) !== value.name) {
36
+ return undefined;
37
+ }
38
+ return value;
39
+ }
40
+ catch {
41
+ return undefined;
42
+ }
43
+ }
44
+ /**
45
+ * Codex, Antigravity, DeepSeek Harness, and Muse intentionally consume the
46
+ * same portable project skill surface (<repo>/.agents/skills). A projection
47
+ * written for any member is managed ownership for the others when the
48
+ * desired payload is otherwise byte-identical.
49
+ */
50
+ export function providersShareProjectionSurface(actual, expected) {
51
+ const shared = new Set(['antigravity', 'codex', 'deepseek-harness', 'muse']);
52
+ return actual === expected || (shared.has(actual) && shared.has(expected));
53
+ }
54
+ export function isManagedTarget(targetPath, expectedName, expectedProvider) {
55
+ if (!fs.existsSync(targetPath))
56
+ return false;
57
+ try {
58
+ const targetStat = fs.lstatSync(targetPath);
59
+ const marker = path.join(targetPath, AGENT_SKILL_MANAGED_MARKER);
60
+ const sidecar = readDeploymentSidecar(targetPath, expectedName);
61
+ return (targetStat.isDirectory()
62
+ && !targetStat.isSymbolicLink()
63
+ && fs.lstatSync(marker).isFile()
64
+ && !fs.lstatSync(marker).isSymbolicLink()
65
+ && fs.readFileSync(marker, 'utf8') === MARKER_CONTENT
66
+ && sidecar !== undefined
67
+ && (expectedProvider === undefined
68
+ || providersShareProjectionSurface(sidecar.provider, expectedProvider)));
69
+ }
70
+ catch {
71
+ return false;
72
+ }
73
+ }
74
+ //# sourceMappingURL=deployment-ownership.js.map
@@ -0,0 +1,114 @@
1
+ // Resolve existing provider skill roots and projection limits.
2
+ import os from 'node:os';
3
+ import path from 'node:path';
4
+ import { getProviderDefinition, normalizeProviderDefinitionId } from '../providers/provider-definitions.js';
5
+ import { resolveHermesHomePath } from '../providers/hermes-home.js';
6
+ import { museXdgSkillsDirRemediation, resolveMuseXdgSkillsDir } from '../providers/muse-paths.js';
7
+ import { GROKBOT_SKILLS_DIR_ENV, grokbotMissingRootRemediation, resolveGrokbotSkillsDir } from '../providers/grokbot-paths.js';
8
+ import { fail } from './deployment-types.js';
9
+ function resolvedHome(options) {
10
+ return path.resolve(options.homeDir ?? os.homedir());
11
+ }
12
+ export function resolvePolicy(target, options) {
13
+ const provider = normalizeProviderDefinitionId(target);
14
+ if (!provider) {
15
+ fail('AS_DEPLOY_PROVIDER', `unknown Agent Skills target "${target}"`);
16
+ }
17
+ const definition = getProviderDefinition(provider);
18
+ if (!definition) {
19
+ fail('AS_DEPLOY_PROVIDER', `provider definition is unavailable for "${provider}"`);
20
+ }
21
+ const namespace = definition.skillNamespace;
22
+ const reasons = [];
23
+ const warnings = [];
24
+ let root = namespace.pathType === 'home-dir'
25
+ ? path.join(resolvedHome(options), namespace.skillsBaseDir)
26
+ : path.join(path.resolve(options.projectDir), namespace.skillsBaseDir);
27
+ let status = 'native';
28
+ let supported = true;
29
+ let appendToDescription;
30
+ let maxDescriptionLength;
31
+ switch (provider) {
32
+ case 'codex':
33
+ root = path.join(path.resolve(options.projectDir), '.agents', 'skills');
34
+ status = 'projected';
35
+ maxDescriptionLength = namespace.maxDescriptionLength;
36
+ reasons.push('uses the project .agents/skills compatibility surface without the legacy 100/500 truncation transform');
37
+ break;
38
+ case 'factory':
39
+ status = 'projected';
40
+ appendToDescription = namespace.appendToDescription;
41
+ reasons.push('applies the Factory description guidance before strict validation');
42
+ break;
43
+ case 'grokbot': {
44
+ // Fail closed: never invent ~/grokbot-skills or ~/.grokbot.
45
+ const configured = resolveGrokbotSkillsDir(process.env);
46
+ if (!configured) {
47
+ root = '';
48
+ status = 'unsupported';
49
+ supported = false;
50
+ reasons.push(grokbotMissingRootRemediation(process.env));
51
+ warnings.push(`Agent Skills deploy for grokbot requires absolute ${GROKBOT_SKILLS_DIR_ENV}; no filesystem root was invented`);
52
+ }
53
+ else {
54
+ root = configured;
55
+ reasons.push(`uses the operator-configured ${GROKBOT_SKILLS_DIR_ENV} skills root with strict managed ownership markers`);
56
+ }
57
+ break;
58
+ }
59
+ case 'hermes':
60
+ if (options.homeDir === undefined) {
61
+ root = resolveHermesHomePath('skills');
62
+ }
63
+ reasons.push('uses the active HERMES_HOME skills surface with strict managed ownership markers');
64
+ break;
65
+ case 'muse': {
66
+ // ADR scope rule 1: the default projection is the project
67
+ // <repo>/.agents/skills surface shared with antigravity, codex, and
68
+ // deepseek-harness. Muse reads both that root and its XDG user root,
69
+ // so writing the user root by default would list a skill twice.
70
+ // #234: an explicit user scope resolves the documented XDG root at
71
+ // deploy time — never ~/.muse — and bad XDG metadata fails closed.
72
+ if (options.scope === 'user') {
73
+ const home = resolvedHome(options);
74
+ const configured = resolveMuseXdgSkillsDir(process.env, home);
75
+ if (!configured) {
76
+ root = '';
77
+ status = 'unsupported';
78
+ supported = false;
79
+ reasons.push(museXdgSkillsDirRemediation(process.env, home));
80
+ warnings.push('Agent Skills deploy for muse requires a valid absolute XDG_CONFIG_HOME; no filesystem root was invented');
81
+ }
82
+ else {
83
+ root = configured;
84
+ reasons.push('uses the Muse XDG user skills root ($XDG_CONFIG_HOME/muse/skills, default ~/.config/muse/skills) with strict managed ownership markers');
85
+ }
86
+ }
87
+ else {
88
+ reasons.push('uses the project .agents/skills surface shared with antigravity, codex, and deepseek-harness');
89
+ }
90
+ break;
91
+ }
92
+ case 'openhuman':
93
+ status = 'projected';
94
+ reasons.push('uses the verified global one-level ~/.openhuman/skills layout');
95
+ break;
96
+ case 'windsurf':
97
+ status = 'projected';
98
+ reasons.push('uses one skill bundle directly below the one-level .windsurf/skills surface');
99
+ break;
100
+ default:
101
+ reasons.push('provider exposes a native recursive Agent Skills bundle surface');
102
+ }
103
+ return {
104
+ provider,
105
+ root,
106
+ status,
107
+ supported,
108
+ reasons,
109
+ warnings,
110
+ appendToDescription,
111
+ maxDescriptionLength,
112
+ };
113
+ }
114
+ //# sourceMappingURL=deployment-policy.js.map