@marcoscale98/pi-extensible-workflows 5.19.1-fork.1 → 6.2.1-fork.1

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 (123) hide show
  1. package/CHANGELOG.md +77 -0
  2. package/README.md +2 -2
  3. package/dist/src/agent-execution.d.ts +43 -10
  4. package/dist/src/agent-execution.js +365 -127
  5. package/dist/src/background-widget.d.ts +0 -1
  6. package/dist/src/background-widget.js +4 -9
  7. package/dist/src/decoders.d.ts +2 -3
  8. package/dist/src/decoders.js +33 -37
  9. package/dist/src/execution.d.ts +2 -0
  10. package/dist/src/execution.js +5 -5
  11. package/dist/src/host-delivery.js +4 -8
  12. package/dist/src/host-navigator.js +5 -2
  13. package/dist/src/host-phases.d.ts +1 -0
  14. package/dist/src/host-recovery.d.ts +6 -6
  15. package/dist/src/host-recovery.js +14 -22
  16. package/dist/src/host-runtime.js +56 -5
  17. package/dist/src/host-view.d.ts +1 -1
  18. package/dist/src/host-view.js +17 -15
  19. package/dist/src/host.js +62 -87
  20. package/dist/src/index.d.ts +1 -2
  21. package/dist/src/index.js +1523 -1630
  22. package/dist/src/index.js.map +3 -3
  23. package/dist/src/paths.d.ts +7 -6
  24. package/dist/src/paths.js +24 -15
  25. package/dist/src/persistence.d.ts +1 -0
  26. package/dist/src/persistence.js +1 -0
  27. package/dist/src/pi-runtime-runner.js +4 -1
  28. package/dist/src/registry.d.ts +9 -7
  29. package/dist/src/registry.js +28 -70
  30. package/dist/src/runtime/agent-runner.d.ts +2 -0
  31. package/dist/src/session-lease.d.ts +1 -1
  32. package/dist/src/session-lease.js +45 -11
  33. package/dist/src/settings.d.ts +6 -3
  34. package/dist/src/settings.js +36 -47
  35. package/dist/src/store.d.ts +3 -1
  36. package/dist/src/store.js +17 -1
  37. package/dist/src/trajectory.d.ts +0 -1
  38. package/dist/src/trajectory.js +2 -3
  39. package/dist/src/types.d.ts +100 -44
  40. package/dist/src/types.js +4 -7
  41. package/dist/src/utils.d.ts +3 -2
  42. package/dist/src/utils.js +20 -10
  43. package/dist/src/validation.d.ts +8 -2
  44. package/dist/src/validation.js +122 -86
  45. package/dist/starter/index.js +8 -9
  46. package/dist/starter/index.js.map +1 -1
  47. package/dist/starter/review-loop.js +8 -7
  48. package/dist/subagents/index.js +654 -814
  49. package/dist/subagents/index.js.map +3 -3
  50. package/dist/subagents/src/contracts.d.ts +4 -3
  51. package/dist/subagents/src/contracts.js +2 -2
  52. package/dist/subagents/src/index.d.ts +1 -1
  53. package/dist/subagents/src/index.js +1 -2
  54. package/dist/subagents/src/manager.js +49 -70
  55. package/dist/subagents/src/navigator.js +3 -14
  56. package/dist/subagents/src/view.d.ts +0 -1
  57. package/dist/subagents/src/view.js +2 -16
  58. package/dist/subagents/src/worktree.js +1 -1
  59. package/dist/trajectory/assets/index.html +8 -8
  60. package/dist/trajectory/index.js +487 -891
  61. package/dist/trajectory/index.js.map +3 -3
  62. package/dist/trajectory/src/assets/index.html +8 -8
  63. package/dist/trajectory/src/index.js +126 -86
  64. package/dist/trajectory/src/server.js +264 -25
  65. package/dist/trajectory/src/server.js.map +3 -3
  66. package/dist/trajectory/src/startup-mutex.d.ts +17 -0
  67. package/dist/trajectory/src/startup-mutex.js +172 -0
  68. package/examples/workflow-extension-template/README.md +4 -7
  69. package/examples/workflow-extension-template/extension.test.mjs +4 -8
  70. package/examples/workflow-extension-template/index.js +0 -3
  71. package/package.json +5 -5
  72. package/skills/pi-extensible-workflows/SKILL.md +10 -8
  73. package/src/agent-execution.ts +339 -127
  74. package/src/background-widget.ts +4 -10
  75. package/src/decoders.ts +31 -37
  76. package/src/execution.ts +5 -5
  77. package/src/host-delivery.ts +4 -8
  78. package/src/host-navigator.ts +4 -2
  79. package/src/host-phases.ts +1 -1
  80. package/src/host-recovery.ts +20 -26
  81. package/src/host-runtime.ts +44 -6
  82. package/src/host-view.ts +18 -11
  83. package/src/host.ts +62 -113
  84. package/src/index.ts +1 -2
  85. package/src/paths.ts +18 -12
  86. package/src/persistence.ts +1 -0
  87. package/src/pi-runtime-runner.ts +3 -1
  88. package/src/registry.ts +27 -63
  89. package/src/runtime/agent-runner.ts +2 -0
  90. package/src/session-lease.ts +34 -6
  91. package/src/settings.ts +35 -47
  92. package/src/store.ts +18 -2
  93. package/src/trajectory.ts +2 -4
  94. package/src/types.ts +71 -30
  95. package/src/utils.ts +18 -9
  96. package/src/validation.ts +102 -79
  97. package/starter/index.ts +0 -1
  98. package/starter/review-loop.ts +8 -7
  99. package/starter/roles/developer.md +0 -1
  100. package/starter/roles/oracle.md +0 -1
  101. package/starter/roles/researcher.md +0 -1
  102. package/starter/roles/reviewer.md +0 -1
  103. package/starter/roles/scout.md +0 -1
  104. package/subagents/README.md +8 -14
  105. package/subagents/src/contracts.ts +3 -4
  106. package/subagents/src/index.ts +2 -3
  107. package/subagents/src/manager.ts +45 -125
  108. package/subagents/src/navigator.ts +4 -13
  109. package/subagents/src/view.ts +4 -14
  110. package/subagents/src/worktree.ts +1 -1
  111. package/trajectory/src/assets/index.html +8 -8
  112. package/trajectory/src/index.ts +106 -82
  113. package/trajectory/src/server.ts +44 -8
  114. package/trajectory/src/startup-mutex.ts +127 -0
  115. package/dist/src/roles.d.ts +0 -70
  116. package/dist/src/roles.js +0 -326
  117. package/dist/starter/roles/developer.md +0 -6
  118. package/dist/starter/roles/oracle.md +0 -18
  119. package/dist/starter/roles/researcher.md +0 -20
  120. package/dist/starter/roles/reviewer.md +0 -19
  121. package/dist/starter/roles/scout.md +0 -18
  122. package/examples/workflow-extension-template/roles/reviewer.md +0 -4
  123. package/src/roles.ts +0 -327
package/src/roles.ts DELETED
@@ -1,327 +0,0 @@
1
- import { readFileSync, readdirSync, statSync } from "node:fs";
2
- import { basename, dirname, extname, join, resolve } from "node:path";
3
- import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
4
- import type { AgentDefinition, AgentResourceSelectorSources, AgentResourceSelectors, ContextFileScope, ModelSpec, WorkflowExtensionMetadata, WorkflowExtensionSettings, WorkflowRoleDirectoryRegistration } from "./types.js";
5
- import { registeredWorkflowRoleDirectoryRegistrations } from "./registry.js";
6
- import { resolveWorkflowSettings, validateContextFileScopes, validateSelectorList, validateWorkflowExtensionSettings, workflowSettingsPath } from "./settings.js";
7
- import { assertModelThinking, deepFreeze, object, errorText, fail, isNodeError, modelAliasName, modelCapability, resourcePatternHasMagic, resolveModelReference, selectResourcesByLayers, unmatchedResourcePatterns } from "./utils.js";
8
- import { canonicalPath, extensionIdentity } from "./paths.js";
9
-
10
- const ROLE_DIRECTORY = "pi-extensible-workflows";
11
- // Preserve the role-file base when a discovered definition is resolved again through the public API.
12
- const roleDefinitionPaths = new WeakMap<AgentDefinition, string>();
13
-
14
- export function parseRoleMarkdown(content: string, strict = false, rolePath?: string): AgentDefinition {
15
- if (!strict) {
16
- if (!content.startsWith("---\n")) return { prompt: content };
17
- const end = content.indexOf("\n---", 4);
18
- if (end < 0) return { prompt: content };
19
- const meta: Record<string, string> = {};
20
- for (const line of content.slice(4, end).split("\n")) {
21
- const match = /^(model|tools|skills|extensions|description|overrideSystemPrompt|override_system_prompt|is_system_prompt|contextFiles|extensionSettings|disabledAgentResources|thinking)\s*:\s*(.+)$/.exec(line.trim());
22
- if (match?.[1] === "disabledAgentResources") fail("INVALID_METADATA", "disabledAgentResources is no longer supported; use skills, extensions, and tools selectors");
23
- if (match?.[1] === "thinking") fail("INVALID_METADATA", "Role thinking is not supported; put it on model as provider/model:thinking");
24
- if (match?.[1] && match[2]) meta[match[1]] = match[2].trim();
25
- }
26
- const unquote = (v: string) => v.replace(/^['"]|['"]$/g, "");
27
- const parseList = (value: string | undefined): string[] | undefined => value === undefined ? undefined : value.replace(/^\[|\]$/g, "").split(",").map((entry) => unquote(entry.trim())).filter(Boolean);
28
- const tools = parseList(meta.tools);
29
- const skills = parseList(meta.skills);
30
- const extensions = parseList(meta.extensions);
31
- let extensionSettings: unknown;
32
- if (meta.extensionSettings !== undefined) {
33
- try { extensionSettings = JSON.parse(meta.extensionSettings) as unknown; }
34
- catch (error) { fail("INVALID_METADATA", `Invalid role extensionSettings: ${errorText(error)}`); }
35
- }
36
- const rolePathValue = rolePath ?? "<role>";
37
- const normalizedExtensionSettings = validateWorkflowExtensionSettings(extensionSettings, rolePathValue, "INVALID_METADATA");
38
- const definition: AgentDefinition = { prompt: content.slice(end + 4).replace(/^\n/, "") };
39
- if (meta.model) {
40
- const model = unquote(meta.model);
41
- assertModelThinking(model, "Role model");
42
- definition.model = model;
43
- }
44
- if (meta.description) definition.description = unquote(meta.description);
45
- if (tools) definition.tools = tools;
46
- if (skills) definition.skills = skills;
47
- if (extensions) definition.extensions = extensions;
48
- if (normalizedExtensionSettings !== undefined) definition.extensionSettings = normalizedExtensionSettings;
49
- const overrideSystemPrompt = meta.overrideSystemPrompt ?? meta.override_system_prompt ?? meta.is_system_prompt;
50
- const contextFiles = meta.contextFiles ? meta.contextFiles.replace(/^\[|\]$/g, "").split(",").map((scope) => unquote(scope.trim())).filter(Boolean) : undefined;
51
- const normalizedContextFiles = validateContextFileScopes(contextFiles, "role");
52
- if (overrideSystemPrompt) definition.overrideSystemPrompt = overrideSystemPrompt === "true";
53
- if (normalizedContextFiles) definition.contextFiles = normalizedContextFiles;
54
- return definition;
55
- }
56
- const normalized = content.replace(/\r\n?/g, "\n");
57
- if (normalized.startsWith("---\n") && normalized.indexOf("\n---", 3) < 0) fail("INVALID_METADATA", "Role frontmatter is missing its closing delimiter");
58
- let parsed: ReturnType<typeof parseFrontmatter>;
59
- try { parsed = parseFrontmatter(content); }
60
- catch (error) { fail("INVALID_METADATA", `Invalid role frontmatter: ${errorText(error)}`); }
61
- if (!object(parsed.frontmatter)) fail("INVALID_METADATA", "Role frontmatter must be an object");
62
- const { model, tools, skills, extensions, extensionSettings, description, contextFiles } = parsed.frontmatter;
63
- if (Object.prototype.hasOwnProperty.call(parsed.frontmatter, "disabledAgentResources")) fail("INVALID_METADATA", "disabledAgentResources is no longer supported; use skills, extensions, and tools selectors");
64
- if (Object.prototype.hasOwnProperty.call(parsed.frontmatter, "thinking")) fail("INVALID_METADATA", "Role thinking is not supported; put it on model as provider/model:thinking");
65
- const overrideSystemPrompt = parsed.frontmatter.overrideSystemPrompt ?? parsed.frontmatter.override_system_prompt ?? parsed.frontmatter.is_system_prompt;
66
- if (model !== undefined && (typeof model !== "string" || model.trim() === "")) fail("INVALID_METADATA", "Role model must be a non-empty string");
67
- if (description !== undefined && (typeof description !== "string" || description.trim() === "" || description.length > 1024 || /[\r\n]/.test(description))) fail("INVALID_METADATA", "Role description must be a non-empty single-line string of at most 1024 characters");
68
- if (overrideSystemPrompt !== undefined && typeof overrideSystemPrompt !== "boolean") fail("INVALID_METADATA", "Role overrideSystemPrompt must be a boolean");
69
- const normalizedContextFiles = validateContextFileScopes(contextFiles, rolePath ?? "<role>");
70
- const rolePathValue = rolePath ?? "<role>";
71
- const normalizedTools = validateSelectorList(tools, rolePathValue, "tools", "INVALID_METADATA");
72
- const normalizedSkills = validateSelectorList(skills, rolePathValue, "skills", "INVALID_METADATA");
73
- const normalizedExtensions = validateSelectorList(extensions, rolePathValue, "extensions", "INVALID_METADATA");
74
- const normalizedExtensionSettings = validateWorkflowExtensionSettings(extensionSettings, rolePathValue, "INVALID_METADATA");
75
- const normalizedDescription = typeof description === "string" ? description.trim() : undefined;
76
- const normalizedModel = typeof model === "string" ? model.trim() : undefined;
77
- if (normalizedModel !== undefined) assertModelThinking(normalizedModel, "Role model");
78
- const definition: AgentDefinition = { prompt: parsed.body };
79
- if (normalizedDescription !== undefined) definition.description = normalizedDescription;
80
- if (normalizedModel !== undefined) definition.model = normalizedModel;
81
- if (normalizedTools !== undefined) definition.tools = normalizedTools;
82
- if (normalizedSkills !== undefined) definition.skills = normalizedSkills;
83
- if (normalizedExtensions !== undefined) definition.extensions = normalizedExtensions;
84
- if (normalizedExtensionSettings !== undefined) definition.extensionSettings = normalizedExtensionSettings;
85
- if (typeof overrideSystemPrompt === "boolean") definition.overrideSystemPrompt = overrideSystemPrompt;
86
- if (normalizedContextFiles !== undefined) definition.contextFiles = normalizedContextFiles;
87
- return definition;
88
- }
89
-
90
- export function workflowRoleDirectories(agentDir = getAgentDir()): readonly string[] {
91
- return [join(agentDir, ROLE_DIRECTORY, "roles")];
92
- }
93
-
94
- function projectRoleDirectories(root: string): readonly string[] {
95
- return [join(root, ROLE_DIRECTORY, "roles")];
96
- }
97
-
98
- type RoleDirectorySource = { path: string; extension?: WorkflowExtensionMetadata; builtin?: true };
99
- export type WorkflowRoleDirectoryInput = string | WorkflowRoleDirectoryRegistration;
100
- type RoleFile = { name: string; path: string; source: RoleDirectorySource };
101
- function roleDirectorySources(dirs: readonly WorkflowRoleDirectoryInput[]): RoleDirectorySource[] {
102
- const seen = new Set<string>();
103
- return dirs.flatMap((value) => {
104
- const source = typeof value === "string" ? { path: value } : { path: value.path, extension: value.extension, ...(value.builtin === true ? { builtin: true as const } : {}) };
105
- if (seen.has(source.path)) return [];
106
- seen.add(source.path);
107
- return [source];
108
- });
109
- }
110
- function roleDirectoryLabel(source: RoleDirectorySource, extension = true): string {
111
- return source.extension ? `Extension "${source.extension.headline}" (${source.extension.version})` : extension ? "Registered workflow extension" : "Standard workflow";
112
- }
113
- function isRoleFile(dir: string, entry: import("node:fs").Dirent): boolean {
114
- if (extname(entry.name) !== ".md") return false;
115
- if (entry.isFile()) return true;
116
- if (!entry.isSymbolicLink()) return false;
117
- try { return statSync(join(dir, entry.name)).isFile(); }
118
- catch (error) { if (isNodeError(error, "ENOENT")) return false; throw error; }
119
- }
120
- function scanRoleFiles(dirs: readonly WorkflowRoleDirectoryInput[], extension: boolean): RoleFile[] {
121
- const files: RoleFile[] = [];
122
- for (const source of roleDirectorySources(dirs)) {
123
- let entries: import("node:fs").Dirent[];
124
- try { entries = readdirSync(source.path, { withFileTypes: true }); }
125
- catch (error) {
126
- if (!extension && isNodeError(error, "ENOENT")) continue;
127
- fail("INVALID_METADATA", `${roleDirectoryLabel(source, extension)} role directory "${source.path}" could not be scanned: ${errorText(error)}`);
128
- }
129
- for (const entry of entries) if (isRoleFile(source.path, entry)) files.push({ name: basename(entry.name, ".md"), path: join(source.path, entry.name), source });
130
- }
131
- return files.sort((left, right) => left.name.localeCompare(right.name) || left.path.localeCompare(right.path));
132
- }
133
-
134
- export interface RoleDiscoveryOptions {
135
- cwd: string;
136
- agentDir?: string;
137
- projectTrusted?: boolean;
138
- extensionRoleDirectories?: readonly WorkflowRoleDirectoryInput[];
139
- }
140
- export interface RoleResourceCandidates {
141
- skills?: readonly string[];
142
- extensions?: readonly string[];
143
- tools?: readonly string[];
144
- }
145
- export interface RoleResolutionOptions extends RoleDiscoveryOptions {
146
- definition?: AgentDefinition;
147
- definitions?: Readonly<Record<string, AgentDefinition>>;
148
- model?: string;
149
- modelOverride?: ModelSpec;
150
- rootModel?: ModelSpec;
151
- rootTools?: ReadonlySet<string> | readonly string[];
152
- inheritedTools?: readonly string[];
153
- availableModels?: ReadonlySet<string>;
154
- knownModels?: ReadonlySet<string>;
155
- modelAliases?: Readonly<Record<string, string>>;
156
- blockedAliases?: ReadonlySet<string>;
157
- blockedAliasTargets?: Readonly<Record<string, string>>;
158
- settingsPath?: string;
159
- selectorSources?: AgentResourceSelectorSources;
160
- resources?: RoleResourceCandidates;
161
- tools?: readonly string[];
162
- skills?: readonly string[];
163
- extensions?: readonly string[];
164
- contextFiles?: readonly ContextFileScope[];
165
- effectiveTools?: readonly string[];
166
- }
167
- export interface ResolvedRole {
168
- name?: string;
169
- definition?: AgentDefinition;
170
- model?: ModelSpec;
171
- requestedModel?: string;
172
- tools?: readonly string[];
173
- prompt: string;
174
- overrideSystemPrompt: boolean;
175
- systemPrompt: { mode: "override" | "append"; text: string };
176
- contextFiles?: readonly ContextFileScope[];
177
- extensionSettings?: Readonly<WorkflowExtensionSettings>;
178
- selectorSources: AgentResourceSelectorSources;
179
- selectorLayers: { skills: readonly (readonly string[] | undefined)[]; extensions: readonly (readonly string[] | undefined)[]; tools: readonly (readonly string[] | undefined)[] };
180
- selectedSkills?: readonly string[];
181
- selectedExtensions?: readonly string[];
182
- unmatchedSkills?: readonly string[];
183
- unmatchedExtensions?: readonly string[];
184
- unmatchedTools?: readonly string[];
185
- }
186
-
187
- type RoleEntry = { name: string; path: string; definition: AgentDefinition; source: RoleDirectorySource };
188
- function roleEntries(dirs: readonly WorkflowRoleDirectoryInput[], extension: boolean): Record<string, RoleEntry> {
189
- const files = scanRoleFiles(dirs, extension);
190
- const starterFiles = files.filter(({ source }) => source.builtin === true);
191
- const regularFiles = files.filter(({ source }) => source.builtin !== true);
192
- if (extension) {
193
- const byName = new Map<string, RoleFile[]>();
194
- for (const file of regularFiles) byName.set(file.name, [...(byName.get(file.name) ?? []), file]);
195
- for (const [name, matches] of byName) if (matches.length > 1) fail("INVALID_METADATA", `Duplicate extension role "${name}": ${matches.map(({ path, source }) => `${roleDirectoryLabel(source)} role directory "${source.path}" (${path})`).join("; ")}`);
196
- }
197
- const read = (roleFiles: readonly RoleFile[]): Record<string, RoleEntry> => Object.fromEntries(roleFiles.map(({ name, path, source }) => {
198
- try {
199
- const definition = parseRoleMarkdown(readFileSync(path, "utf8"), true, path);
200
- roleDefinitionPaths.set(definition, path);
201
- return [name, { name, path, source, definition }];
202
- }
203
- catch (error) {
204
- if (extension) fail("INVALID_METADATA", `${roleDirectoryLabel(source)} role directory "${source.path}" contains invalid role "${name}" at "${path}": ${errorText(error)}`);
205
- throw error;
206
- }
207
- }));
208
- return extension ? { ...read(starterFiles), ...read(regularFiles) } : read(files);
209
- }
210
- type ResolvedRoleDiscoveryOptions = { cwd: string; agentDir: string; projectTrusted: boolean; extensionRoleDirectories: readonly WorkflowRoleDirectoryInput[] };
211
- function discoveryInput(input: RoleDiscoveryOptions): ResolvedRoleDiscoveryOptions {
212
- return { cwd: input.cwd, agentDir: input.agentDir ?? getAgentDir(), projectTrusted: input.projectTrusted ?? true, extensionRoleDirectories: input.extensionRoleDirectories ?? registeredWorkflowRoleDirectoryRegistrations() };
213
- }
214
- function discoveredRoleEntries(input: RoleDiscoveryOptions): Record<string, RoleEntry> {
215
- const resolved = discoveryInput(input);
216
- return {
217
- ...roleEntries(resolved.extensionRoleDirectories, true),
218
- ...roleEntries(workflowRoleDirectories(resolved.agentDir), false),
219
- ...(resolved.projectTrusted ? roleEntries(projectRoleDirectories(join(resolved.cwd, ".pi")), false) : {}),
220
- };
221
- }
222
- export function loadProjectAgentDefinitions(cwd: string): Readonly<Record<string, AgentDefinition>> {
223
- return deepFreeze(Object.fromEntries(Object.entries(roleEntries(projectRoleDirectories(join(cwd, ".pi")), false)).map(([name, entry]) => [name, entry.definition])));
224
- }
225
- export function discoverRoles(input: RoleDiscoveryOptions): Readonly<Record<string, AgentDefinition>> {
226
- return deepFreeze(Object.fromEntries(Object.entries(discoveredRoleEntries(input)).map(([name, entry]) => [name, entry.definition])));
227
- }
228
- export function loadRole(name: string, input: RoleDiscoveryOptions): AgentDefinition {
229
- const entry = discoveredRoleEntries(input)[name];
230
- if (!entry) fail("UNKNOWN_AGENT_TYPE", `Unknown agent role: ${name}`);
231
- return entry.definition;
232
- }
233
- export function loadAgentDefinitions(cwd: string, agentDir = getAgentDir(), projectTrusted = true, extensionRoleDirectories: readonly WorkflowRoleDirectoryInput[] = registeredWorkflowRoleDirectoryRegistrations()): Readonly<Record<string, AgentDefinition>> {
234
- return discoverRoles({ cwd, agentDir, projectTrusted, extensionRoleDirectories });
235
- }
236
-
237
- export function canonicalExtensionSelector(selector: string, base = process.cwd()): string {
238
- const negated = selector.startsWith("!");
239
- const body = negated ? selector.slice(1) : selector;
240
- // Built-in extensions are named `builtin:<name>`, not by a path.
241
- if (body === "*" || body === "**" || body.startsWith("**/") || body.startsWith("builtin:")) return selector;
242
- const resolved = resolve(base, body);
243
- if (resourcePatternHasMagic(body)) return `${negated ? "!" : ""}${resolved}`;
244
- return `${negated ? "!" : ""}${canonicalPath(resolved)}`;
245
- }
246
- function selectorsFromSettings(settings: { skills?: readonly string[]; extensions?: readonly string[]; tools?: readonly string[] }): AgentResourceSelectors {
247
- return { ...(settings.skills === undefined ? {} : { skills: settings.skills }), ...(settings.extensions === undefined ? {} : { extensions: settings.extensions }), ...(settings.tools === undefined ? {} : { tools: settings.tools }) };
248
- }
249
- function rootToolNames(value: ReadonlySet<string> | readonly string[] | undefined): readonly string[] | undefined {
250
- return value === undefined ? undefined : value instanceof Set ? [...value] : [...value];
251
- }
252
- function roleDefinitionFor(name: string | undefined, options: RoleResolutionOptions): { definition?: AgentDefinition; path?: string } {
253
- if (name === undefined) return {};
254
- if (options.definition !== undefined) {
255
- const path = roleDefinitionPaths.get(options.definition);
256
- return { definition: options.definition, ...(path === undefined ? {} : { path }) };
257
- }
258
- if (options.definitions?.[name] !== undefined) {
259
- const definition = options.definitions[name];
260
- const path = roleDefinitionPaths.get(definition);
261
- return { definition, ...(path === undefined ? {} : { path }) };
262
- }
263
- const entries = discoveredRoleEntries(options);
264
- const entry = entries[name];
265
- if (!entry) fail("UNKNOWN_AGENT_TYPE", `Unknown agent role: ${name}`);
266
- return entry;
267
- }
268
- /** Without a supplied root/tool/resource boundary, this API reports selector layers but does not infer available resources; tools and model remain undefined when no candidates are supplied. When selector sources are supplied, model aliases default to none and blocked aliases are not applied unless provided. */
269
- export function resolveRole(name: string | undefined, options: RoleResolutionOptions): ResolvedRole {
270
- const { definition, path } = roleDefinitionFor(name, options);
271
- const settings = options.selectorSources === undefined ? resolveWorkflowSettings(options.cwd, options.projectTrusted ?? true, options.settingsPath ?? workflowSettingsPath(options.agentDir ?? getAgentDir())) : undefined;
272
- const baseSources = options.selectorSources ?? { global: selectorsFromSettings(settings?.global ?? {}), project: selectorsFromSettings(settings?.project ?? {}) };
273
- const canonicalSources = (sources: AgentResourceSelectorSources): AgentResourceSelectorSources => ({
274
- ...sources,
275
- global: { ...sources.global, ...(sources.global.extensions === undefined ? {} : { extensions: sources.global.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }) },
276
- project: { ...sources.project, ...(sources.project.extensions === undefined ? {} : { extensions: sources.project.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }) },
277
- ...(sources.role === undefined ? {} : { role: { ...sources.role, ...(sources.role.extensions === undefined ? {} : { extensions: sources.role.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }) } }),
278
- ...(sources.call === undefined ? {} : { call: { ...sources.call, ...(sources.call.extensions === undefined ? {} : { extensions: sources.call.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }) } }),
279
- });
280
- const roleLayer = definition?.skills !== undefined || definition?.extensions !== undefined || definition?.tools !== undefined ? { ...(definition.skills === undefined ? {} : { skills: definition.skills }), ...(definition.extensions === undefined ? {} : { extensions: definition.extensions.map((selector) => canonicalExtensionSelector(selector, path ? dirname(path) : options.cwd)) }), ...(definition.tools === undefined ? {} : { tools: definition.tools }) } : baseSources.role;
281
- const callLayer = options.skills !== undefined || options.extensions !== undefined || options.tools !== undefined ? { ...(options.skills === undefined ? {} : { skills: options.skills }), ...(options.extensions === undefined ? {} : { extensions: options.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }), ...(options.tools === undefined ? {} : { tools: options.tools }) } : baseSources.call;
282
- const selectorSources = canonicalSources({ global: baseSources.global, project: baseSources.project, ...(roleLayer === undefined ? {} : { role: roleLayer }), ...(callLayer === undefined ? {} : { call: callLayer }) });
283
- const callSelectors = selectorSources.call;
284
- const roleSelectors = selectorSources.role;
285
- const selectorLayers = {
286
- skills: [selectorSources.global.skills, selectorSources.project.skills, roleSelectors?.skills, callSelectors?.skills],
287
- extensions: [selectorSources.global.extensions, selectorSources.project.extensions, roleSelectors?.extensions, callSelectors?.extensions],
288
- tools: [selectorSources.global.tools, selectorSources.project.tools, roleSelectors?.tools, callSelectors?.tools],
289
- };
290
- const resources = options.resources ?? {};
291
- const candidateTools = options.inheritedTools ?? rootToolNames(options.rootTools) ?? resources.tools;
292
- const tools = options.effectiveTools ?? (candidateTools === undefined ? undefined : selectResourcesByLayers(selectorLayers.tools, candidateTools));
293
- const rootTools = rootToolNames(options.rootTools);
294
- if (rootTools !== undefined) {
295
- const outsideEffectiveTool = options.effectiveTools?.find((tool) => !candidateTools?.includes(tool));
296
- if (outsideEffectiveTool) fail("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${outsideEffectiveTool}`);
297
- const outsideCallTool = (options.tools ?? []).find((tool) => !tool.startsWith("!") && !resourcePatternHasMagic(tool) && !candidateTools?.includes(tool));
298
- if (outsideCallTool) fail("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${outsideCallTool}`);
299
- const outsideRootTool = tools?.find((tool) => !rootTools.includes(tool));
300
- if (outsideRootTool) fail("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${outsideRootTool}`);
301
- }
302
- const selectedSkills = resources.skills === undefined ? undefined : selectResourcesByLayers(selectorLayers.skills, resources.skills);
303
- const extensionResources = resources.extensions?.map((extension) => extensionIdentity(extension));
304
- const selectedExtensions = extensionResources === undefined ? undefined : selectResourcesByLayers(selectorLayers.extensions, extensionResources);
305
- const unmatchedSkills = resources.skills === undefined ? undefined : unmatchedResourcePatterns(selectorLayers.skills.flatMap((layer) => layer ?? []), resources.skills);
306
- const unmatchedExtensions = extensionResources === undefined ? undefined : unmatchedResourcePatterns(selectorLayers.extensions.flatMap((layer) => layer ?? []), extensionResources);
307
- const unmatchedTools = candidateTools === undefined ? undefined : unmatchedResourcePatterns(selectorLayers.tools.flatMap((layer) => layer ?? []), candidateTools);
308
- const aliases = options.modelAliases ?? settings?.effective.modelAliases ?? {};
309
- const requestedModel = options.model ?? (definition?.model && definition.thinking && !definition.model.includes(":") ? `${definition.model}:${definition.thinking}` : definition?.model);
310
- const blockedAlias = requestedModel?.split(":", 1)[0];
311
- if (requestedModel !== undefined && blockedAlias && options.blockedAliases?.has(blockedAlias) && !modelAliasName(requestedModel, aliases)) {
312
- const target = options.blockedAliasTargets?.[blockedAlias];
313
- fail("UNKNOWN_MODEL", `Unknown model alias ${requestedModel}${target ? ` resolved to ${target}` : ""}${options.settingsPath ? ` (settings: ${options.settingsPath})` : ""}`);
314
- }
315
- let model = options.modelOverride;
316
- if (model === undefined && requestedModel !== undefined) {
317
- assertModelThinking(requestedModel);
318
- model = resolveModelReference(requestedModel, aliases, options.knownModels ?? options.availableModels, options.settingsPath ?? settings?.sources.modelAliases);
319
- }
320
- if (model === undefined) model = options.rootModel;
321
- const availableModels = options.knownModels ?? options.availableModels ?? (options.rootModel === undefined ? undefined : new Set([modelCapability(options.rootModel)]));
322
- if (model !== undefined && availableModels !== undefined && !availableModels.has(modelCapability(model))) fail("UNKNOWN_MODEL", `Unknown model${requestedModel ? ` ${requestedModel} resolved to ${modelCapability(model)}` : ""}${options.settingsPath ? ` (settings: ${options.settingsPath})` : ""}`);
323
- const prompt = definition?.prompt ?? "";
324
- const overrideSystemPrompt = definition?.overrideSystemPrompt === true;
325
- const contextFiles = options.contextFiles ?? definition?.contextFiles;
326
- return { ...(name === undefined ? {} : { name }), ...(definition === undefined ? {} : { definition }), ...(model === undefined ? {} : { model }), ...(modelAliasName(requestedModel ?? "", aliases) && requestedModel ? { requestedModel } : {}), ...(tools === undefined ? {} : { tools }), prompt, overrideSystemPrompt, systemPrompt: { mode: overrideSystemPrompt ? "override" : "append", text: prompt }, ...(contextFiles === undefined ? {} : { contextFiles: [...contextFiles] }), ...(definition?.extensionSettings === undefined ? {} : { extensionSettings: definition.extensionSettings }), selectorSources, selectorLayers, ...(selectedSkills === undefined ? {} : { selectedSkills }), ...(selectedExtensions === undefined ? {} : { selectedExtensions }), ...(unmatchedSkills === undefined ? {} : { unmatchedSkills }), ...(unmatchedExtensions === undefined ? {} : { unmatchedExtensions }), ...(unmatchedTools === undefined ? {} : { unmatchedTools }) };
327
- }