@agimon-ai/po-workflow 0.0.0-alpha.7 → 0.0.0-alpha.70

package/LICENSE

@@ -1,29 +1,149 @@
-Portions of this software are licensed as follows:
-
-* The browser half of this package, meaning every ".web" routed file under
-  "src/extensions" and the "_components" and "_lib" modules colocated with
-  one, is licensed under the Po Web License defined in "LICENSE.web":
-  free to use, not to redistribute.
-* All other content is licensed under the MIT license below.
-
-MIT License
-
-Copyright (c) 2026 Vuong Ngo
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             Agimon Pty Ltd
+Licensed Work:        Po, the software in the Po source repository and the
+                      packages released from it, in each version released by
+                      the Licensor.
+                      The Licensed Work is (c) 2026 Agimon Pty Ltd.
+                      Material identified as third-party in the "Third-party
+                      components" section at the end of this file or in a
+                      NOTICE file, and any package or directory whose own
+                      license file grants a different license, is not part of
+                      the Licensed Work and remains under its own license.
+Additional Use Grant: You may make production use of the Licensed Work if
+  your use is Eligible Use. "Eligible Use" is production use that falls
+  within at least one of the following:
+
+  (a) Personal Use. Use by an individual for their own personal purposes,
+      and not on behalf of, or for the benefit of, an employer, client, or
+      other Organization. Use by an individual in the course of employment
+      or engagement by an Organization is use by that Organization.
+
+  (b) Small Organization Use. Use by or on behalf of an Organization whose
+      Annual Revenue is less than USD 1,000,000.
+
+  (c) Non-profit, Education and Research Use. Use, regardless of Annual
+      Revenue, by (i) an Organization registered or recognized as a
+      non-profit or charitable organization under the laws of its
+      jurisdiction, for its non-profit purposes; (ii) an accredited school,
+      college, or university, for teaching, learning, or academic research;
+      or (iii) a publicly funded research institution, for its research.
+
+  (d) Service Provider Use. Use by a consultant, contractor, agency, or other
+      service provider, regardless of its own Annual Revenue, solely to
+      build, deploy, host, operate, or support the Licensed Work for a client
+      whose own use would be Eligible Use under (a), (b), or (c). A service
+      provider's use for its own purposes is Eligible Use only if the service
+      provider itself qualifies under (b) or (c).
+
+
+  Hosted services. Offering the Licensed Work to third parties as a hosted
+  or managed service whose primary value is the Licensed Work is Eligible
+  Use only if each such third party's own use would be Eligible Use.
+
+  Definitions. "Organization" means any company, partnership, sole
+  proprietorship, trust, association, government body, or other entity, and
+  includes an individual acting in a business or professional capacity.
+  "Affiliate" means any entity that directly or indirectly controls, is
+  controlled by, or is under common control with an Organization, where
+  "control" means ownership of more than 50% of the voting interests of an
+  entity or the power to direct its management and policies by contract or
+  otherwise. "Annual Revenue" means the total gross revenue of an
+  Organization and all of its Affiliates combined, from all sources and
+  whether or not related to the Licensed Work, for its most recently
+  completed fiscal year, or, if it has not completed a fiscal year, for the
+  twelve months before the use (or since its formation, if shorter),
+  converted into US dollars at the average exchange rate for that period.
+  Proceeds of equity or debt financing are not revenue.
+
+  Threshold. If an Organization stops qualifying under (b), its existing
+  production use remains Eligible Use for 90 days after it stops
+  qualifying, after which it must obtain a commercial license or stop
+  production use. Use that was Eligible Use when it occurred never requires
+  a commercial license after the fact.
+Change Date:          Four years from the date a version of the Licensed Work
+                      is first publicly released by the Licensor.
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please visit: https://agimon.ai/licensing
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -4,8 +4,8 @@ Discover, launch, monitor, control, and recover asynchronous Po workflows.
 
 Part of the [Po distribution](https://www.npmjs.com/package/@agimon-ai/po).
 
-The integration embeds `@agimon-ai/workflow-mcp`. Workflow files describe job dependencies and
-host-executed steps, while Po provides session-scoped tools.
+This package owns the workflow engine and the `workflow-mcp` CLI (`po-workflow-mcp` is an alias).
+Workflow files describe job dependencies and host-executed steps, while Po provides session-scoped tools.
 
 > **Alpha:** workflow and recovery contracts may change between releases.
 
@@ -15,8 +15,8 @@ host-executed steps, while Po provides session-scoped tools.
 
 ## Install
 
-The seeded `modes.yaml` selects Workflow in `default.packages`. Keep it there or select it through
-a layer; its tools remain inactive until Workflow mode is enabled.
+The seeded `modes.yaml` selects the `workflow` layer in `minimal`, `copilot` and `examples`.
+Remove it from a mode to omit Workflow there. No minor-mode activation is required.
 
 ## Define a workflow
 
@@ -49,6 +49,116 @@ 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. Their methods take a call context as the last argument.
+- `signal`: the session tools lifetime, aborted on session disposal or mounting failure.
+- `context`: a call context for `fs` and `shell`, aborted with `signal`. Inside `bind(run)`, pass
+  `run.context` instead, which also aborts when that exec ends.
+
+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.
+
+## Step instructions
+
+A workflow can give its managed Po agent steps their own instructions file:
+
+```yaml
+instructions: ./AGENTS.md
+```
+
+The file replaces the AGENTS.md files the step session would discover from its working directory; it
+does not add to them. The path resolves relative to the declaring YAML and is inherited through
+`imports` as a default, like `tools`. A missing or unreadable file fails the step session rather than
+running it without instructions. Shell steps and external Claude/Codex CLI runners ignore it.
+
 ## Launch and monitor
 
 Core tools are:
@@ -61,6 +171,20 @@ Core tools are:
 Launch returns after the run is registered, not after all jobs complete. Use status for progress
 and wait for a completion notification.
 
+## Dynamic workflows
+
+The package also supplies the `dynamicWorkflow` code-mode namespace: tracked Mastra
+workflows composed with `then`, `parallel`, `branch` and bounded `foreach`, with live
+`team.run` transcripts. It is available when the `workflow` layer is selected, with no
+minor-mode gate. Inside a YAML run, a `customRun` step's agent can use it
+for fan-out whose shape is only known at run time, and the run view shows those runs under
+that step. See the [code-mode guide](src/prompts/codemode-how-to-workflow/SKILL.md).
+Tracker state is in memory per session; it is not persisted with the run record.
+
+Select the `workflow` layer in `modes.yaml`. Existing default-package entries still work
+and deduplicate with the layer. No configuration migration runs, and persisted
+`minorModes: [workflow]` has no effect.
+
 ## Storage, concurrency, and lifecycle
 
 Registry data defaults to `$HOME/.workflow-mcp`; set `WORKFLOW_MCP_HOME` to relocate it. Persisted
@@ -84,16 +208,16 @@ 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 publishes `workflow-recovery`, `po-author-workflow` for writing workflow
-definitions, and `po-use-workflow` for launching, monitoring, and recovering runs while Workflow
-mode is active. Deactivating Workflow mode hides them; cached files may remain.
+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
 
 In a server (web cockpit) session, a launch does not run in the session that asked for it. The
 session creates a child **workflow session** (provenance `workflow-session`), nested under it in the
-rail, and hands it the launch. The workflow session owns the run (`PI_SESSION_ID`), runs its step
-sessions, and has Workflow mode on, so its agent can troubleshoot and recover the run. The run's
+rail, and hands it the launch. The workflow session owns the run (`PO_SESSION_ID`), runs its step
+sessions, so its agent can troubleshoot and recover the run without a workflow minor mode. The run's
 environment also carries `PO_WORKFLOW_LAUNCHER_SESSION_ID`, naming the launching session, which
 lists the run in its Activity group, is told when it ends, and may read its status.
 
@@ -127,20 +251,31 @@ dialog in the overlay slot, the Activity group's run rows (a handed-off run open
 session), their stores, and the `workflow_runs` session channel, compiled into the cockpit bundle
 by `po-web`'s build. Each surface keeps its components in a colocated `_components` folder and
 its stores and helpers in `_lib`.
-The hub-side data source ships behind the `./web-hub` subpath and reads the workflow registry
-(run.json plus progress.ndjson) exactly as the engine writes it. Both halves are declared by the
-`poWeb` block in package.json.
+The hub-side data source lives in the package's backend API and reads the workflow registry
+(run.json plus progress.ndjson) exactly as the engine writes it. The `poServer` and `poWeb`
+blocks in package.json declare the backend and browser contributions.
+
+## Upgrading from the separate engine
+
+The engine now ships inside `@agimon-ai/po-workflow`. Both `workflow-mcp` and
+`po-workflow-mcp` invoke that package's CLI. Storage paths and registry records are unchanged.
+
+Let active runs finish before replacing an installation, or retain their exact old Node and CLI
+payloads until they finish. A run-local `bin/workflow-mcp` launcher contains absolute paths to the
+engine that created it. Never rewrite a live launcher or hot-swap its engine.
+
+In repositories with canonical `.po/hooks.yaml`, replace the old package's CLI path with
+`node_modules/@agimon-ai/po-workflow/dist/cli.mjs`, then regenerate the frontend settings with that
+repository's hook emitter. Installation alone does not migrate existing hook registries.
 
 ## License
 
-MIT, except this package's browser half (the `.web` routed files under `src/extensions` and the
-`_components` and `_lib` modules colocated with one), which is source available under the Po
-Web License (see `LICENSE.web`): free to use, including commercially, but not to redistribute.
+Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See [LICENSE](LICENSE) and https://agimon.ai/licensing.
 
 ## Native execution contract
 
-Agent steps require an effective `runConfig.majorMode`; delegated workflows require top-level `runConfig.majorMode` before their owner child is created. Selection projects major mode, minor modes, profile and domains, adding the workflow minor mode once. `subagentModel` and `subagentThinking` set Team preferences independently of the step model.
+Agent steps require an effective `runConfig.majorMode`; delegated workflows require top-level `runConfig.majorMode` before their owner child is created. Selection projects major mode, minor modes, profile and domains unchanged. `subagentModel` and `subagentThinking` set Team preferences independently of the step model.
 
-The native host requires execution-state inspection before creating agent steps. After settlement it waits for idle, no pending messages and a known background snapshot without core holds or holding-provider errors before checking decisions. Unknown ownership waits closed without consuming reminders; stops interrupt reads and retry delays.
+The native host requires execution-state inspection before creating agent steps. After settlement it waits for idle, no pending messages and a known background snapshot without core holds or holding-provider errors before checking decisions. Unknown ownership waits closed without consuming reminders; stops interrupt reads and retry delays. Running commands stop holding an inline step after five idle minutes, but its decision gate still runs before session release.
 
 Delegated successes are informational. Errors wake the workflow owner through durable custom-message admission; the launcher gets an error notification, not an agent-waking failure completion. Diagnosis stays local. Recovery, pause, resume and stop are request-driven. User-requested stops do not trigger diagnosis or automatic restart.