@agimon-ai/po-workflow 0.0.0-alpha.56 → 0.0.0-alpha.57

package/README.md

@@ -49,6 +49,101 @@ needs, and `run` and `interactiveRun` steps each get their own RMUX pane. Each r
 log in `engine.log` in its run directory. See `docs/automation.md` for the full contract and the
 CLI fallback.
 
+## Job-specific tools
+
+Managed Po agent steps can receive a workflow-owned `jobTools` code-mode namespace and a pinned
+`workflow-job-tools` skill. Select a folder at workflow level as a default, or override it per job:
+
+```yaml
+name: summarize
+runConfig:
+  majorMode: copilot
+tools: ./tools/shared
+jobs:
+  report:
+    tools: ./tools/report
+    steps:
+      - name: Summarize
+        customRun: Read workflow-job-tools, discover jobTools, then summarize this job.
+```
+
+The folder must contain JavaScript `index.mjs` and a non-empty `SKILL.md`. Paths are resolved relative
+to the YAML that declares them, before imports and job-template inheritance. Empty paths, control
+characters and URL specifiers are rejected. Parsing, listing and inspection never execute the module.
+A job's main steps, `preJob` and `postJob` use its selection or the workflow default. `repair.tools`
+overrides the default for repair triage. Global phases use the workflow default.
+
+Only trusted, managed Po `customRun` and in-process `interactiveRun` agent sessions receive these
+tools, not shell steps, ordinary sessions, or external Claude/Codex CLI runners. Each session uses its
+captured workflow config. Global `pre` can run before the worktree YAML is reparsed, so its tools are
+not necessarily selected from that worktree. Step `cwd`, `WORKTREE_PATH` and environment variables do
+not select or resolve the tools folder.
+
+`index.mjs` default-exports a factory, called once per managed session with:
+
+- `sessionId` and the admitted working directory `cwd`.
+- `workflow`: the trusted `PoWorkflowContextService`, including the captured config, job/step identity,
+  admitted `jobEnvironment` and `stepEnvironment`, and workflow state reader.
+- Injected `fs` and `shell` capabilities.
+- `signal`: the session tools lifetime, aborted on session disposal or mounting failure.
+
+Return the existing `PoCodemodeNamespace` contract: name `jobTools`, a non-empty one-line `summary`
+(maximum 600 characters), TypeScript `declarations` for discovery, and `bind(run)`. Bind returns flat
+named async methods with JSON arguments and results. Each exec gets a fresh binding; keep per-session
+state inside the factory, not at module scope. Validate method inputs and honour `run.signal` in long
+operations. Use `run.onDispose` for exec-owned cleanup. The host refuses foreign sessions and calls
+after cancellation/disposal, and detaches JSON values in both directions. Return `null`, not
+`undefined`, for no output.
+
+A minimal runnable `tools/report/index.mjs`:
+
+```js
+export default function createJobTools({ sessionId, workflow, signal }) {
+  signal.throwIfAborted();
+  return {
+    name: 'jobTools',
+    summary: 'Describe the current workflow job with a supplied label.',
+    declarations: `declare const jobTools: {
+      describe(input: { label: string }): Promise<{ job: string; label: string }>;
+    };`,
+    bind(run) {
+      if (run.sessionId !== sessionId) throw new Error('Wrong session.');
+      return {
+        async describe(input) {
+          run.signal.throwIfAborted();
+          if (!input || typeof input.label !== 'string' || !input.label.trim())
+            throw new Error('label must be a non-empty string.');
+          return { job: workflow.job, label: input.label.trim() };
+        },
+      };
+    },
+  };
+}
+```
+
+Corresponding `tools/report/SKILL.md`:
+
+```md
+# Report tools
+
+Use jobTools.describe to label the current job before writing its summary.
+Discover jobTools for the current signature, then call it through exec.
+Do not guess a label or repeat an effect after cancellation without checking its outcome.
+```
+
+Agents read the pinned skill, call `discover({ namespace: 'jobTools' })`, then use
+`exec` with `return await jobTools.describe({ label: 'Verification' });`. Keep guidance in `SKILL.md`
+and signatures in `declarations`. Optional namespace `approval` policies are preserved and enforced
+by the existing code-mode approval path; each policy must name a returned method. An approval request
+is not permission to bypass the normal approval flow.
+
+Tools are trusted workflow code running with the host's privileges, not sandboxed code. Review the
+folder before launching. Native import caches modules by file URL; editing `index.mjs` at the same
+path requires a host restart. There is no direct TypeScript loading, hot reload, or external CLI
+bridge. A missing file or invalid factory fails the managed step session rather than silently
+omitting its selected tools. The namespace and skill mount and dispose together; disposing them does
+not stop the owning workflow or change its recovery rules.
+
 ## Launch and monitor
 
 Core tools are:
@@ -98,8 +193,9 @@ adopts the eligible failure, validates the evidence, and transfers ownership to
 Live controls remain scoped to the owning session. Recovery does not launch a second copy beside a
 still-running job and does not guarantee that parent-session work survives shutdown.
 
-The package ships two skills: pinned, ungated `codemode-how-to-workflow` for both namespaces,
-and unpinned, Help-gated `help-how-to-workflow` for authoring and maintenance.
+The package ships two skills: pinned, ungated `codemode-how-to-workflow` for workflow code-mode
+namespaces and selected job tools, and unpinned, Help-gated `help-how-to-workflow` for authoring and
+maintenance. A selected tools folder also supplies the managed session's pinned `workflow-job-tools` skill.
 
 ## Workflow sessions
 

package/dist/{RecoverWorkflowService-C1lWL4fC.cjs → RecoverWorkflowService-DL5itVWA.cjs}

@@ -12,6 +12,7 @@ let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_rolldown_runtime.__toESM(node_fs_promises, 1);
 let node_readline = require("node:readline");
+let node_url = require("node:url");
 let proper_lockfile = require("proper-lockfile");
 let node_perf_hooks = require("node:perf_hooks");
 let node_os = require("node:os");
@@ -250,7 +251,9 @@ const PreBlockSchema = zod.z.object({
 	steps: zod.z.array(StepSchema).optional()
 });
 const JobHookBlockSchema = zod.z.object({ steps: zod.z.array(StepSchema).optional() });
+const WorkflowToolsPathSchema = zod.z.string().min(1).refine((value) => value.trim().length > 0 && !/^[a-z][a-z0-9+.-]*:/iu.test(value.trimStart()) && value.split("").every((character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127), "Workflow tools must be a local filesystem path without URL schemes or control characters.").describe("Tools folder relative to its declaring YAML file, containing index.mjs and SKILL.md.");
 const JobSchema = zod.z.object({
+	tools: WorkflowToolsPathSchema.optional(),
 	"runs-on": zod.z.string().optional(),
 	needs: zod.z.union([zod.z.string(), zod.z.array(zod.z.string())]).optional(),
 	extends: zod.z.union([zod.z.string(), zod.z.array(zod.z.string())]).optional(),
@@ -329,6 +332,7 @@ const RunDirectorySchema = zod.z.object({
 });
 const WorkflowSchema = zod.z.object({
 	name: zod.z.string().optional(),
+	tools: WorkflowToolsPathSchema.optional(),
 	tags: zod.z.array(zod.z.string().trim().min(1)).optional().describe("Tags used to categorize and filter workflow definitions."),
 	workspace: zod.z.string().optional(),
 	runner: zod.z.string().optional().describe("Default runner key for step command maps when no CLI runner is provided."),
@@ -1771,6 +1775,21 @@ var WorkflowRegistryService = class {
 			ownerSessionId
 		});
 	}
+	/** A person's Stop remains terminal even when the owning process is already gone. */
+	async requestStaleStop(workspace, runKey, reason, expectedRunId, ownerSessionId) {
+		const request = {
+			reason: reason?.trim() || void 0,
+			requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			runId: expectedRunId,
+			schemaVersion: 1
+		};
+		await this.reconcileStaleRunningRecord(this.resolveWorkspace(workspace), this.slugifySegment(runKey, FALLBACK_RUN_KEY), {
+			runId: expectedRunId,
+			ownerSessionId,
+			stop: request
+		});
+		return request;
+	}
 	/**
 	* Ensure the stage directories exist for the workspace.
 	*/
@@ -1884,7 +1903,18 @@ var WorkflowRegistryService = class {
 		const runningRecordPath = (0, node_path.resolve)(runningDir, RUN_RECORD_FILENAME$1);
 		return this.writeCoordinator.forKey(runningRecordPath)(async () => {
 			const currentRecord = await this.readRunRecord(runningRecordPath);
-			if (expected !== void 0 && (currentRecord.runId !== expected.runId || currentRecord.env?.PI_SESSION_ID !== expected.ownerSessionId) || !currentRecord.pid || this.isProcessAlive(currentRecord.pid)) return currentRecord;
+			if (expected !== void 0 && (currentRecord.runId !== expected.runId || currentRecord.env?.PI_SESSION_ID !== expected.ownerSessionId)) {
+				if (expected.stop) throw new Error(`Workflow run ownership changed: ${workspace}/${runKey}`);
+				return currentRecord;
+			}
+			if (!currentRecord.pid || this.isProcessAlive(currentRecord.pid)) {
+				if (expected?.stop) throw new Error(`Workflow process is not known to be dead: ${workspace}/${runKey}`);
+				return currentRecord;
+			}
+			if (expected?.stop) {
+				if (currentRecord.stage !== RUNNING_STAGE) throw new Error(`Workflow run is no longer controllable: ${workspace}/${runKey}`);
+				await this.writeAtomic((0, node_path.resolve)(runningDir, STOP_REQUEST_FILENAME), expected.stop);
+			}
 			if (currentRecord.stage !== RUNNING_STAGE) {
 				const stageDir = this.getRunDirectory(workspace, currentRecord.stage, runKey);
 				await this.removeFileIfExists((0, node_path.resolve)(runningDir, FINALIZING_FILENAME));
@@ -1903,14 +1933,15 @@ var WorkflowRegistryService = class {
 				failedJob: currentRecord.executionCursor?.job ?? currentRecord.failedJob,
 				finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
 				outcome: "interrupted",
-				stage: ERROR_STAGE$2
+				stage: ERROR_STAGE$2,
+				...expected?.stop ? { resume: void 0 } : {}
 			};
+			await this.writeRunRecord(runningRecordPath, finalRecord);
 			(0, _agimon_ai_po_core_platform.getOrThrow)(await this.runtime.fs.remove(errorDir, {
 				recursive: true,
 				force: true
 			}, this.runtime.ioContext));
 			(0, _agimon_ai_po_core_platform.getOrThrow)(await this.runtime.fs.renameFile(runningDir, errorDir, this.runtime.ioContext));
-			await this.writeRunRecord((0, node_path.resolve)(errorDir, RUN_RECORD_FILENAME$1), finalRecord);
 			return finalRecord;
 		});
 	}
@@ -2437,6 +2468,7 @@ var WorkflowParserService = class {
 			this.githubSha = "local";
 		}
 		const workflow = WorkflowSchema.parse((0, js_yaml.load)(content));
+		this.resolveToolsPaths(workflow, resolved);
 		if (workflow.imports) await this.resolveImports(workflow, resolved);
 		if (!workflow.jobs || Object.keys(workflow.jobs).length === 0) throw new Error("No jobs found in workflow file");
 		this.resolveExtends(workflow);
@@ -2455,11 +2487,20 @@ var WorkflowParserService = class {
 		const parsed = (0, js_yaml.load)(content);
 		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Workflow template must be a YAML object: ${resolved}`);
 		const workflow = parsed;
+		this.resolveToolsPaths(workflow, resolved);
 		workflow.jobs ??= {};
 		if (workflow.imports) await this.resolveImports(workflow, resolved);
 		workflow.jobs ??= {};
 		return workflow;
 	}
+	/** Resolve before merging so imported jobs and defaults keep their declaring file's origin. */
+	resolveToolsPaths(workflow, workflowPath) {
+		for (const declaration of [
+			workflow,
+			...Object.values(workflow.jobs ?? {}),
+			workflow.repair
+		]) if (declaration?.tools !== void 0) declaration.tools = (0, node_path.resolve)((0, node_path.dirname)(workflowPath), WorkflowToolsPathSchema.parse(declaration.tools));
+	}
 	/**
 	* Render a command template into the shell command a step runs.
 	*
@@ -2601,7 +2642,8 @@ var WorkflowParserService = class {
 	*   - system-prompt: concatenated (imported + main)
 	*   - commands, choices: merged per name (main overrides imported)
 	*   - runConfig, sessionConfig: merged per key (main overrides imported)
-	* Imports are processed in order; later imports override earlier ones.
+	*   - tools: scalar default (main wins, otherwise first imported selection)
+	* Imports are processed in order; earlier merged values act as main overrides.
 	* Circular imports are detected and throw an error.
 	*/
 	async resolveImports(workflow, workflowPath, visited = /* @__PURE__ */ new Set()) {
@@ -2614,7 +2656,9 @@ var WorkflowParserService = class {
 			if (!await (0, _agimon_ai_po_core_platform.pathExists)(this.runtime.fs, resolvedImport, this.runtime.ioContext)) throw new Error(`Imported workflow file not found: ${resolvedImport} (from ${normalizedPath})`);
 			const importContent = (0, _agimon_ai_po_core_platform.getOrThrow)(await this.runtime.fs.readTextFile(resolvedImport, this.runtime.ioContext));
 			const imported = (0, js_yaml.load)(importContent);
+			this.resolveToolsPaths(imported, resolvedImport);
 			if (imported.imports) await this.resolveImports(imported, resolvedImport, visited);
+			workflow.tools ??= imported.tools;
 			if (imported.env) workflow.env = {
 				...imported.env,
 				...workflow.env
@@ -2694,7 +2738,7 @@ var WorkflowParserService = class {
 	*   - postJob.steps: template steps prepended before job postJob steps
 	*   - env: merged (job overrides template)
 	*   - system-prompt: concatenated (template + job)
-	*   - all other fields: job overrides template
+	*   - runs-on, strategy, context, tools: inherited when not set on the job
 	* Template jobs are removed from the jobs map after resolution.
 	*/
 	resolveExtends(workflow) {
@@ -2743,6 +2787,7 @@ var WorkflowParserService = class {
 		if (template["runs-on"] && !job["runs-on"]) job["runs-on"] = template["runs-on"];
 		if (template.strategy && !job.strategy) job.strategy = template.strategy;
 		if (template.context && !job.context) job.context = template.context;
+		job.tools ??= template.tools;
 	}
 	mergeJobHookSteps(job, template, hookKey) {
 		const templateSteps = template[hookKey]?.steps ?? [];
@@ -5109,6 +5154,10 @@ function createWorkflowHost(options) {
 			input: process.stdin,
 			output: process.stdout
 		}),
+		importJobTools: (path) => import(
+			/* @vite-ignore */
+			(0, node_url.pathToFileURL)(path).href
+),
 		openArtifact,
 		writeExclusive: (path, content) => (0, node_fs_promises.writeFile)(path, content, {
 			flag: "wx",
@@ -11359,6 +11408,12 @@ Object.defineProperty(exports, "WorkflowStageSchema", {
 		return WorkflowStageSchema;
 	}
 });
+Object.defineProperty(exports, "WorkflowToolsPathSchema", {
+	enumerable: true,
+	get: function() {
+		return WorkflowToolsPathSchema;
+	}
+});
 Object.defineProperty(exports, "connectNativeTerminal", {
 	enumerable: true,
 	get: function() {
@@ -11486,4 +11541,4 @@ Object.defineProperty(exports, "workflowShellOutput", {
 	}
 });
 
-//# sourceMappingURL=RecoverWorkflowService-C1lWL4fC.cjs.map
+//# sourceMappingURL=RecoverWorkflowService-DL5itVWA.cjs.map