@agimon-ai/po-workflow 0.0.0-alpha.55 → 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