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

package/CHANGELOG.md

@@ -1,6 +1,83 @@
 # Changelog
 ## Unreleased
 
+## [6.2.1] - 2026-10-13
+
+### New capabilities
+
+- Registered functions can create persistent agent handles with `context.agent.create({ name, ... })` and `handle.send(...)`, with the same rules as scripts. Handle journal identity is scoped by function invocation, branch, worktree, and name. The bundled `reviewLoop` now uses one persistent developer and a fresh reviewer each iteration.
+
+### Fixes
+
+- Trajectory displays agent and system prompts as complete escaped plain text, so XML-style sections such as `<addendum>`, `<skills>`, and `<project_context>` remain visible instead of being interpreted as HTML inside Markdown. Browser regressions verify line breaks and safe rendering.
+- `agent(...)` and `handle.send(...)` now deliver the supplied text as the whole user message, on first and later turns. The repeated Workflow/Agent/Phase/Parent header, ownership paragraph, and `Task:` wrapper are gone. The `workflow_result` once-per-turn contract moved into that tool's description, child ownership into the `agent` tool description, and retry or soft-budget notes into separate control text after the task (a steered message on local sessions, appended to the pane launch prompt on Herdr; custom transports that do not set `turnControlDelivered` get the steered message). The system prompt is unchanged, so prompt caching is unaffected.
+
+### Documentation and metadata
+
+- Clarified that the workflow `model` option is optional; omitting it uses the configured defaults.
+- Updated the core package description and keywords to include codemode scripts.
+
+## [6.2.0] - 2026-10-10
+
+### New capabilities
+
+- Selecting a phase or registered function in the workflow navigator now shows total tokens, cost, and elapsed time across all its agents, including nested agents (#318).
+
+### Fixes
+
+- Launch now checks static agent calls inside registered functions that the script calls by name, so an unknown model for a later agent fails before the workflow starts. A computed `outputSchema` no longer makes a call dynamic (#309).
+- On Linux, session lease liveness uses the process start time from `/proc/<pid>/stat` instead of the `/proc/<pid>` entry time, so a live session owner is no longer reported dead (#307).
+- In the wide workflow navigator, the details column follows the scrolled tree, so details for a selected node further down a long workflow stay visible (#317).
+- Model references keep colon-bearing and namespaced model IDs, such as `openrouter/deepseek/deepseek-v4.1-flash:nitro:high`. The final `:` segment is read as a thinking level only when it names one, so `provider/model:turbo` now fails as `INVALID_METADATA` instead of `UNKNOWN_MODEL` (#314).
+- Concurrent Trajectory starts in one agent directory now share one server whose lock always names the process answering `/health`. A lock whose owner is alive but does not answer within the startup budget, or a lock that cannot be read, is kept and the attach fails with a clear error, instead of a second server being started beside it. Process liveness is checked against the kernel start time, not the `/proc` entry time, and Trajectory sends SIGKILL only to a process whose recorded start time still matches; a stale server that cannot be confirmed stopped keeps its lock and fails the attach (#315).
+
+## [6.1.0] - 2026-10-08
+
+**This minor version contains breaking changes.** Shipping them as 6.1.0 shortly after 6.0.0 is an explicit operator choice, not a SemVer-compliant version. Read the migration notes before upgrading.
+
+### Breaking changes
+
+- Roles are now interpreted only by the explicitly enabled optional `@piewf/pi-ext-roles` extension. Core and CLI have no roles dependency, discovery, typed role fields, `/roles` export, `pi-role` bridge or legacy role paths. Without the plugin, unknown agent options are opaque JSON and ignored. The five fallback roles belong to the independent package.
+- Generic `agentPreparationHooks` optionally validate original options with a schema, then prepare concrete configuration before model/resource validation. Workflow agents, handles, nested agents, standalone subagents and doctor share preparation and root/parent capability enforcement. Consumer selectors remain ordered defaults, not extra authorization ceilings.
+- New runs freeze generic prepared configurations before dispatch. Workflow identity version 6 and standalone configuration version 1 reject previous formats without migration. Retry/resume reuse configuration; new identities resolve current settings. Extension code and skill/AGENTS/SYSTEM/APPEND bytes are reread, not frozen.
+- Doctor uses `--agent-options <json>` and `agentInspection`, not role targets or `--role`. Bundles require explicit plugin resources/dependencies instead of role inference. Obsolete compatibility upgrade/warning checks are removed; generic and extension-owned regressions plus the local paired SDK/CLI harness replace their still-relevant coverage.
+- Role descriptions append to Pi's structured prompt channel, preserving existing append instructions and dynamic provider/tool prefixes (#311); they never force the entire system prompt.
+
+### Migration
+
+- To keep using `role` options, install `@piewf/pi-ext-roles` 0.2.0 or newer and enable it explicitly as a Pi extension next to workflows. Core and CLI no longer install or load it.
+- Roles and shared settings are read only from the roles package paths: `~/.pi/agent/pi-ext-roles/{settings.json,roles/}` and authorized project `.pi/pi-ext-roles/{settings.json,roles/}`. Legacy workflow role paths are ignored; move files manually, nothing is rewritten.
+- Runs persisted before 6.1.0 cannot be resumed or retried. Finish them before upgrading, then relaunch them as new runs.
+- Role text is appended through Pi's structured system-prompt append channel. Only roles with `overrideSystemPrompt: true` replace the base prompt.
+- `pi-role` is owned only by the independent `@piewf/pi-ext-roles` package, which works without workflows. Upgrade an old global `@piewf/cli` first; never overwrite the binary with `--force`.
+- Prepared options stay bounded by root and parent tool ceilings, project trust and `excludeTools`; setup hooks cannot change the agent cwd.
+
+### Fixes
+
+- Restored pre-6 behavior: `excludeTools` for workflow, nested and standalone agents, also in the `agent` and `subagents_run` tool schemas (exact names as in Pi, applied after preparation, bounded by parent ceilings and frozen with each logical agent's configuration; patterns and `workflow_result` are rejected, unknown names warn); `resources_discover` skills for root, nested and standalone agents, attributed per resource generation with Pi's path normalization; static preparation failures, including unavailable models and unknown roles, fail before shell, tool or run effects; nested children keep core error codes and their parent's structural scope under their own identity; unrelated extension load failures are CLI warnings; bundled factories run without a Pi API again and keep their module source.
+- Launch inspection covers only completely static agent options (handles only when no send adds options) and stops on cancellation, also after the session lease. Nested children are new spawns of their parent's attempt, with identities per parent spawn: after retry or cold resume they prepare against current configuration.
+- After a CLI extension load failure, every workflow registration must declare a `source` that is a loaded extension entry or a portable bundle module, or the CLI stops before running anything (a factory may register and then fail). Agent options that no such preparation hook declares in its `optionsSchema` fail with `INVALID_METADATA` instead of being ignored, also after paused resume, cold resume or retry. Setup hooks cannot reintroduce an excluded or outside-ceiling root tool as a same-named custom tool, and `excludeTools` names, own or inherited, also remove custom tools of those names.
+- Preparation context adds `projectCwd` and `defaults.dynamicModelAliasNames`, so plugins can read launch-project configuration inside worktrees and order dynamic aliases below their own static aliases. A paused run resumed after an alias change prepares new agents with the refreshed aliases. A hook passing on a virtual `workflow/<alias>` root model gets its physical target.
+- Setup hooks still cannot change the agent cwd, including to a project subdirectory; `SessionInput.cwd` is now read-only. This deliberate deviation from pre-6 prevents loading another directory's trust, settings and `.pi` resources.
+
+## [6.0.0] - 2026-10-07
+
+### Breaking changes
+
+- Roles are owned by `@piewf/pi-ext-roles`, now a registry dependency of core and CLI. `registerWorkflowExtension({ roleDirectories })` is removed and fails with migration guidance. Register packaged roles separately with `registerRoleContribution(pi, { owner: import.meta.url, roleDirectories: ["./roles"] })`; keep workflow `source` for provenance and re-export portable bundles that used the removed field.
+- The `pi-role` binary moves from `@piewf/cli` to `@piewf/pi-ext-roles`. Upgrade the old global CLI first, then install the roles package without forced binary overwrites. The retained `@piewf/cli/pi-role` import is a compatibility adapter, not the binary owner.
+- Fallback roles no longer select models or supply workflow-specific model aliases. Configure a per-call model or an overriding role/shared alias explicitly when preserving an old fallback model choice.
+
+### Migration
+
+- Workflow/subagent users receive the roles library automatically; a separately enabled roles plugin is not required. Move shared roles and settings to `~/.pi/agent/pi-ext-roles/` and `.pi/pi-ext-roles/` when ready. Workflow aliases/selectors remain consumer overrides. No user files are rewritten.
+- Legacy workflow role paths and parser/resolver imports remain temporarily supported, with one TUI migration warning per session when applicable. No compatibility removal date is scheduled. Native `pi-role` does not read legacy workflow paths; migrate its files before using it.
+- Native `pi-role` starts one Pi process from PATH. Role tool selectors control declared loadout, not a sandbox. Native tool flags remain ceilings; partial context scopes are unsupported unless suppressed with `--no-context-files`, and role/shared `extensionSettings` are ignored by the launcher. Workflow/subagent consumers retain settings delivery, partial context filtering, captured configuration, recovery and runtime ownership. See the [migration guide](https://vekexasia.github.io/pi-extensible-workflows/roles.html#migration).
+
+### Verification
+
+- Package verification uses the published roles artifact, without a sibling checkout or local dependency staging. `scripts/verify-role-upgrade.py` exercises registry installation in an isolated Pi, the `5.19.1` to major-candidate upgrade, TUI/reload, legacy settings and role precedence, binary handover, migrated contributors and re-exported bundles against a local provider.
+
 ## [5.19.1] - 2026-10-05
 
 ### New capabilities

package/README.md

@@ -11,7 +11,7 @@ The repository [README](https://github.com/vekexasia/pi-extensible-workflows#rea
 ## Install
 
 Requires Node.js 22.19 or newer. This is trusted Pi host code with the same filesystem and process access as Pi.
-The core installation includes workflow orchestration, the `reviewLoop` starter for implementation-and-review cycles, packaged `developer`/`reviewer`/`scout`/`oracle`/`researcher` roles with ready-made slash commands (`/scout`, `/oracle`, `/review`, `/parallel-review`, `/review-loop`, `/deep-research`, and more), and durable standalone subagent tools. See the [Subagents guide](https://vekexasia.github.io/pi-extensible-workflows/subagents.html) for the bundled tools.
+The core installation includes workflow orchestration, the `reviewLoop` starter for implementation-and-review cycles, ready-made slash commands (`/scout`, `/oracle`, `/review`, `/parallel-review`, `/review-loop`, `/deep-research`, and more), and durable standalone subagent tools. Role options in starters and slash commands require the separately enabled `@piewf/pi-ext-roles` Pi extension; core does not ship or interpret roles. See the [Subagents guide](https://vekexasia.github.io/pi-extensible-workflows/subagents.html) for the bundled tools.
 Trajectory live monitoring is included in the package. Restart existing Pi processes after upgrading the package so their publisher protocol matches the detached Trajectory server.
 
 ```sh
@@ -35,7 +35,7 @@ Launch with a non-empty `name` and exactly one of `script` or `scriptPath`. Regi
 
 ## Programmatic integration
 
-The package exports the workflow registry, runtime, persistence, validation, settings, role, lifecycle, and local Pi session APIs used by trusted hosts and extensions.
+The package exports the workflow registry, runtime, persistence, validation, settings, generic agent preparation, lifecycle, and local Pi session APIs used by trusted hosts and extensions.
 
 Direct consumers of `createLocalPiSession()` receive a session with extensions already bound. Always `await session.dispose()` so `session_shutdown` runs before the native session is released; disposal is idempotent.
 

package/dist/src/agent-execution.d.ts

@@ -85,18 +85,17 @@ export interface PiResourceInspection {
     }[];
     readonly systemPromptSource?: string;
 }
-import type { AgentAccounting, AgentActivity, AgentContinuity, AgentIdentity, AgentResourcePolicy, AgentResourceSelectors, AgentSetup, AgentSetupSummary, AgentTransport, AgentTransportContext, ContextFileScope, JsonSchema, JsonValue, LiveSessionHandoff, ModelSpec, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentSession, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowRunContext } from "./types.js";
-import { type AgentDefinition, type AgentState } from "./types.js";
+import type { AgentPreparationContext, PreparedAgentConfiguration, RegisteredAgentPreparationHook, AgentAccounting, AgentActivity, AgentContinuity, AgentIdentity, AgentResourcePolicy, AgentResourceSelectors, AgentSetup, AgentSetupSummary, AgentTransport, AgentTransportContext, ContextFileScope, JsonSchema, JsonValue, LiveSessionHandoff, ModelSpec, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentSession, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowRunContext } from "./types.js";
+import { type AgentState } from "./types.js";
 import type { RunStore } from "./persistence.js";
-type AgentExecutionRunStore = Pick<RunStore, "recordSystemPrompt" | "validateWorktree" | "worktree" | "snapshotWorktree">;
-export type { AgentAccounting, AgentActivity, AgentInspectionMode, AgentSetup, AgentSetupContext, AgentSetupHook, AgentTransport, AgentTransportContext, PiRuntimeLaunchInfo, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentMessage, WorkflowAgentSession, WorkflowAgentSessionEvent, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowAgentSessionStats, WorkflowAgentTurnResult } from "./types.js";
+type AgentExecutionRunStore = Pick<RunStore, "recordSystemPrompt" | "validateWorktree" | "worktree" | "snapshotWorktree"> & Partial<Pick<RunStore, "load" | "saveAgentConfiguration">>;
+export type { AgentPreparation, AgentPreparationContext, PreparedAgentConfiguration, RegisteredAgentPreparationHook, AgentAccounting, AgentActivity, AgentInspectionMode, AgentSetup, AgentSetupContext, AgentSetupHook, AgentTransport, AgentTransportContext, PiRuntimeLaunchInfo, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentMessage, WorkflowAgentSession, WorkflowAgentSessionEvent, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowAgentSessionStats, WorkflowAgentTurnResult } from "./types.js";
 export interface AgentBudgetHooks {
     beforeAttempt(): void;
     beforeTurn(): void;
     afterTurn(accounting: AgentAccounting, final: boolean): void;
     instruction(): string | undefined;
 }
-export type { AgentDefinition } from "./types.js";
 export interface AgentProviderFailure {
     label: string;
     provider: string;
@@ -122,7 +121,6 @@ export interface AgentExecutionOptions {
     skills?: readonly string[];
     extensions?: readonly string[];
     effectiveTools?: readonly string[];
-    role?: string;
     contextFiles?: readonly ContextFileScope[];
     schema?: JsonSchema;
     retries?: number;
@@ -136,31 +134,53 @@ export interface AgentExecutionOptions {
     agentIdentity?: AgentIdentity;
     inheritedExtensionSettings?: Readonly<WorkflowExtensionSettings>;
     agentNodeId?: string;
+    capabilities?: Readonly<{
+        tools: readonly string[];
+        skills: readonly string[];
+        extensions: readonly string[];
+    }>;
+    parentSkills?: readonly string[];
+    /** Tool names that ancestors excluded; with this agent's own `excludeTools`, they are removed from root and custom tools alike. */
+    inheritedExcludeTools?: readonly string[];
+    projectTrusted?: boolean;
+    configuration?: PreparedAgentConfiguration;
+    onConfiguration?: (configuration: PreparedAgentConfiguration) => void | Promise<void>;
 }
 export interface AgentExecutionRoot {
+    projectTrusted?: boolean;
     cwd: string;
     model: ModelSpec;
     tools: ReadonlySet<string>;
     extensionSettings?: Readonly<WorkflowExtensionSettings> | undefined;
     validateExtensionSettings?: (settings: Readonly<WorkflowExtensionSettings> | undefined, context: WorkflowExtensionSettingsValidatorContext) => void;
     onAgentSettings?: (agentNodeId: string, settings: Readonly<WorkflowExtensionSettings>) => void;
+    onAgentCapabilities?: (agentNodeId: string, capabilities: AgentPreparationContext["capabilities"], projectTrusted: boolean) => void;
     resourceSelectors?: AgentResourceSelectors;
-    agentDefinitions?: Readonly<Record<string, AgentDefinition>>;
     agentDir?: string;
     additionalSkillPaths?: readonly string[];
     availableModels?: ReadonlySet<string>;
     knownModels?: ReadonlySet<string>;
     modelAliases?: Readonly<Record<string, string>>;
+    dynamicModelAliasNames?: readonly string[];
     blockedAliases?: ReadonlySet<string>;
     blockedAliasTargets?: Readonly<Record<string, string>>;
     settingsPath?: string;
     extensionSettingsPath?: string;
     runStore?: AgentExecutionRunStore;
     providerPause?: () => Promise<void>;
+    agentPreparationHooks?: readonly RegisteredAgentPreparationHook[];
     agentSetupHooks?: readonly RegisteredAgentSetupHook[];
     agentResourcePolicy?: () => AgentResourcePolicy | Promise<AgentResourcePolicy>;
     runContext?: Readonly<WorkflowRunContext>;
     onResourceWarning?: (message: string) => void;
+    /**
+     * Load failures this host tolerated and the identities of the extensions it did load. With failures, a non-core option
+     * counts as owned only by the schema of a preparation hook whose `source` is a loaded extension; others fail closed.
+     */
+    extensionLoad?: Readonly<{
+        errors: readonly string[];
+        loaded: readonly string[];
+    }>;
 }
 export interface AgentToolCallProgress {
     id: string;
@@ -222,7 +242,6 @@ export declare function getAgentAttempts(error: unknown): readonly AgentAttempt[
 export declare class WorkflowAgentExecutor {
     private readonly root;
     private readonly transport;
-    private readonly warnedRoleTools;
     constructor(root: AgentExecutionRoot, transport?: AgentTransport);
     setRunContext(runContext: Readonly<WorkflowRunContext>): void;
     resolve(options: AgentExecutionOptions, inheritedTools?: readonly string[]): {
@@ -233,6 +252,7 @@ export declare class WorkflowAgentExecutor {
         systemPromptAppend: string;
         contextFiles?: readonly ContextFileScope[];
     };
+    prepare(options: AgentExecutionOptions, cwd?: string, signal?: AbortSignal, mode?: "execution" | "inspection"): Promise<PreparedAgentConfiguration>;
     execute(task: string, options: AgentExecutionOptions, signal?: AbortSignal, customTools?: readonly ToolDefinition[], setSteer?: (handler: (message: string) => void | Promise<void>) => void, beforeRetry?: () => void): Promise<AgentExecutionResult>;
 }
 export interface ScheduledAgentOptions {
@@ -245,7 +265,6 @@ export interface ScheduledAgentOptions {
     extensions?: readonly string[];
     worktreeOwner?: string;
     model?: string;
-    role?: string;
     contextFiles?: readonly ContextFileScope[];
     schema?: JsonSchema;
     retries?: number;
@@ -255,6 +274,14 @@ export interface ScheduledAgentOptions {
     agentOptions?: Readonly<Record<string, JsonValue>>;
     agentIdentity?: AgentIdentity;
     extensionSettings?: Readonly<WorkflowExtensionSettings>;
+    capabilities?: Readonly<{
+        tools: readonly string[];
+        skills: readonly string[];
+        extensions: readonly string[];
+    }>;
+    projectTrusted?: boolean;
+    configuration?: PreparedAgentConfiguration;
+    inheritedExcludeTools?: readonly string[];
 }
 export type ScheduledAgentResult = {
     id: string;
@@ -297,7 +324,11 @@ type ScheduledNode = {
     resolveCompletion: () => void;
     task: () => Promise<void>;
     restored: boolean;
+    attemptCapabilities?: AgentPreparationContext["capabilities"];
+    attemptProjectTrusted?: boolean;
     steer?: (message: string) => void | Promise<void>;
+    /** Children spawned so far per label; numbers the occurrence of each child's own identity. */
+    childOccurrences?: Map<string, number>;
 };
 export type OwnershipRecord = {
     id: string;
@@ -317,6 +348,8 @@ export declare class FairAgentScheduler {
     addRun(runId: string, limit?: number, beforeLaunch?: () => void, extensionSettings?: Readonly<WorkflowExtensionSettings>): void;
     updateRunLimit(runId: string, limit: number): void;
     setRunExtensionSettings(runId: string, settings: Readonly<WorkflowExtensionSettings> | undefined): void;
+    setConfiguration(agentId: string, configuration: PreparedAgentConfiguration): Promise<void>;
+    setAttemptCapabilities(agentId: string, capabilities: AgentPreparationContext["capabilities"], projectTrusted: boolean): void;
     setExtensionSettings(agentId: string, settings: Readonly<WorkflowExtensionSettings>): void;
     spawn(runId: string, prompt: string, options: ScheduledAgentOptions, parentId?: string): {
         id: string;
@@ -331,7 +364,7 @@ export declare class FairAgentScheduler {
     attemptStarted(id: string): void;
     cancelRun(runId: string): Promise<void>;
     removeRun(runId: string): void;
-    toolsFor(parentId: string, resolveTools?: (role: string | undefined, tools: readonly string[] | undefined, model: string | undefined, inheritedTools: readonly string[], skills: readonly string[] | undefined, extensions: readonly string[] | undefined) => readonly string[]): ToolDefinition[];
+    toolsFor(parentId: string): ToolDefinition[];
     snapshot(): readonly OwnershipRecord[];
     restoreRun(runId: string, limit: number, ownership: readonly OwnershipRecord[], beforeLaunch?: () => void, extensionSettings?: Readonly<WorkflowExtensionSettings>): void;
     flush(runId?: string): Promise<void>;