@humain/humain-code 0.3.8 → 0.4.1

package/docs/flow-profiles.md

@@ -0,0 +1,173 @@
+# Flow Profiles
+
+A Flow profile selects the models, limits, and spend cap for a HUMAIN Code Flow run. Profiles are implemented in `packages/flow/src/profiles/` and validated by the `FlowProfileV1` contract in `@humain/humain-code-contracts/flow-profile`.
+
+## What a profile is
+
+A profile is one JSON document with `schema: "humain-flow-profile"` and `schemaVersion: 1`.
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Pattern `^[a-z0-9][a-z0-9_.:-]{0,127}$`. Also the file name. |
+| `version` | Positive integer. Increases on every save. |
+| `digest` | sha256 hex of the canonical JSON of the document without the `digest` field. |
+| `kind` | `direct` or `flow`. |
+| `label`, `description` | Display text. `label` is 1 to 80 characters, `description` at most 500. |
+| `direct` | Only for `kind: direct`. A `model` and up to 8 `fallbacks`. |
+| `roles` | Only for `kind: flow`. Maps a role to `{ primary, backups (max 8), effort: low\|medium\|high }`. |
+| `sizing` | Optional, `kind: flow` only. Classifier policy id, `mediumAt` and `largeAt` thresholds, `triageRole`, `maxEscalations` (0 or 1). |
+| `limits` | `maxAgents` 1..256, `maxConcurrent` 1..64, `maxDepth` 0..3, `maxRetries` 0..16, `inactivityMs` 1..86400000, `ciWaitMs` 0..86400000. |
+| `spend` | `runCapMicrousd`, `warnAtPct` 1..99, optional `perRoleCapMicrousd`. |
+| `providers` | Optional `preference` list of provider ids (max 16). |
+| `approval`, `builtIn` | `builtIn: true` marks the shipped profiles. User profiles must not set it. |
+
+Role names: `scout`, `worker`, `implementer`, `lead`, `lead_large`, `architect`, `reviewer`, `security_reviewer`, `qa`, `triage`.
+
+Validation rules:
+
+- `kind: direct` requires `direct` and forbids `roles` and `sizing`.
+- `kind: flow` requires `roles.lead`, `roles.worker`, `roles.reviewer`, and `roles.qa`, and forbids `direct`.
+- A model reference may not appear twice in one primary-plus-backups (or model-plus-fallbacks) list.
+- `sizing.thresholds.mediumAt` must be at most `largeAt`.
+- A profile file whose `digest` does not match its content is rejected.
+
+## Built-in profiles
+
+Four read-only profiles ship in `packages/flow/assets/profiles/`. All are `kind: flow` with a run cap of 50000000 microusd.
+
+| Id | lead | worker | reviewer | qa |
+| --- | --- | --- | --- | --- |
+| `premium` | `openai-codex/gpt-6.1-sol` | `openai-codex/gpt-6-luna` | `openai-codex/gpt-6.1-sol` | `anthropic/claude-sonnet-5-5` |
+| `anthropic` | `anthropic/claude-opus-5-5` | `anthropic/claude-sonnet-5` | `anthropic/claude-sonnet-5` | `anthropic/claude-sonnet-5` |
+| `openai` | `openai-codex/gpt-6.1-sol` | `openai-codex/gpt-6-luna` | `openai-codex/gpt-6.1-sol` | `openai-codex/gpt-6.1-sol` |
+| `oss-first` | `humain-node/glm-5.2` | `humain-node/glm-5.2` | `humain-node/glm-5.2` | `humain-node/glm-5.2` |
+
+Built-ins cannot be saved over or deleted (`profile_builtin_readonly`). Clone one to customize it. The ids are reserved: a file with a built-in id in the user directory is reported as `profile_id_reserved` and not loaded.
+
+## Storage layout
+
+All paths are under the agent directory:
+
+```
+<agentDir>/flow/
+  active-profile.json          active pointer
+  profiles/
+    <id>.json                  one file per user profile
+    .store.lock                mutation lock
+    .backups/
+      <id>.v<version>.<ms>-<8hex>.json   previous versions
+      <id>.corrupt.<ms>-<8hex>.json      raw bytes of a removed unparseable profile
+      .<id>.watermark.json               highest RESERVED version for the id (a failed publish can leave a gap)
+```
+
+`active-profile.json` contains `{ "schema": "humain-flow-active-profile", "schemaVersion": 1, "id": "<id>" }`.
+
+Safety checks:
+
+- `flow`, `profiles`, and `.backups` must be real directories (not symlinks), owned by the current user, and not group- or world-writable. Otherwise the store fails with `store_unsafe`. Missing directories are created level by level with mode `0700`; each directory and every ancestor up to the filesystem root are `fsync`ed at the start of every mutation (ancestors that cannot be opened with `EACCES` are skipped), so a retry after a failed `fsync` cannot skip the barrier. Directory `fsync` errors `EINVAL`, `EPERM`, and `EISDIR` (unsupported filesystems) are ignored; all other errors abort the operation.
+- Files are opened without following symlinks, must be regular files, and are limited to 256 KiB (`profile_too_large`).
+- A profile file must be named `<id>.json` and its `id` must match the file name.
+
+## Saving
+
+Every save (editor edit, clone, import) goes through the store lock and:
+
+1. Checks that the on-disk version and digest equal those the edit started from (`baseVersion`, and `baseDigest`, which defaults to the draft's `digest`). A mismatch gives `profile_conflict` (changed on disk) or `profile_exists` (creating a profile that exists).
+2. Sets `version` to the highest of the on-disk version, any backed-up version, and the per-id version watermark (`.backups/.<id>.watermark.json`), plus 1. The watermark records the highest reserved version: a failed publish can leave a gap, and versions are never reused for ids that have a watermark. Ids without a watermark (profiles never saved through the store) can reuse a version number, but the digest check still rejects stale saves. The watermark does not depend on any profile file parsing, so a deleted (even corrupt) and recreated profile never reuses a version, and a stale draft cannot overwrite it. An unreadable or invalid watermark fails the save with `store_unsafe`; it is never reset.
+3. Recomputes `digest` and validates the result.
+4. Writes the previous file bytes to `.backups/<id>.v<version>.<ms>-<8hex>.json`, then `fsync`s the `.backups` directory. If the backup or its `fsync` fails, the save aborts and the original is untouched.
+5. Writes the watermark atomically, then the new file atomically: temp file `<file>.<pid>.<uuid>.tmp`, `fsync`, rename, then `fsync` of the containing directory. Files are created with mode `0600`.
+6. Prunes backups. The newest 10 versions per id and the newest 10 corrupt backups are kept. Pruning never fails a save.
+
+`remove` writes and `fsync`s a backup of the file first (aborting if that fails), deletes the profile, `fsync`s the `profiles` directory, and clears `active-profile.json` if it pointed at that id. An unparseable file is backed up as `<id>.corrupt.<ms>-<8hex>.json`.
+
+### Lock
+
+One lock file, `profiles/.store.lock`, serializes every mutation (save, clone, remove, `use`, import). It is created exclusively with mode `0600` and holds `{ pid, token }`. It is released only if it still holds the owner's token.
+
+If a second writer finds the lock, it fails immediately with `profile_locked`. There is no waiting and no age-based reclamation.
+
+To recover from a stale lock (for example after a crash): confirm no other HUMAIN Code process is editing profiles, then delete `<agentDir>/flow/profiles/.store.lock`.
+
+### Corrupt files
+
+Listing never throws for a bad user profile. Invalid JSON, failed validation, digest mismatch, id/file-name mismatch, oversize files, and reserved ids are reported as problems with the file path and an error code. The remaining profiles still load. Problem messages never include file content.
+
+## Resolution order
+
+`resolveProfile(id?)` picks a profile in this order:
+
+1. The explicit id, if given. Failure throws the underlying error (for example `profile_not_found`).
+2. The active profile from `active-profile.json`.
+3. `premium`, when no active pointer exists.
+
+A malformed active pointer, or one naming a profile that cannot be loaded, throws `active_profile_invalid`. It never falls back silently to `premium`.
+
+The result carries the profile and a frozen reference `{ id, version, digest }`.
+
+## `/flow-profile` command
+
+```
+Usage: /flow-profile [subcommand]
+  list                      list profiles
+  show <id>                 show a profile
+  use <id>                  set the active profile
+  export <id>               print a profile as JSON
+  import <file> [--replace] import a profile file
+  validate <file>           validate a profile file
+No subcommand opens the interactive editor.
+```
+
+- `list` marks the active profile with `*`, shows version and source (`builtin` or `user`), and lists problems.
+- `use` fails if the profile does not load.
+- `import` resolves `<file>` against the working directory. It strips `approval`, rejects built-in ids (`profile_id_reserved`) and files marked `builtIn`, and creates a new profile. If the id exists it fails with `profile_exists` unless `--replace` is given. The imported profile is re-saved, so its version and digest are recomputed.
+- `validate` checks a file without importing it.
+- An unknown subcommand prints the usage text. With no subcommand and no UI, the command runs `list`.
+
+Output is stripped of ANSI escapes and control characters before display, because imported profile text is untrusted.
+
+### Interactive editor
+
+With no subcommand and a UI available, the command opens an editor. The top level lists all profiles (active one marked) and a `Close` entry. Selecting a profile opens its menu:
+
+- Built-in profiles: `View`, `Set active`, `Clone`, `Back`.
+- User profiles: also `Edit role` (only for `kind: flow`), `Edit limits`, `Edit spend cap`, and `Delete` (asks for confirmation).
+
+Edits prompt for text values: role primary as `provider/model`, fallbacks as a comma-separated list (empty keeps the current value, `none` clears), effort, a limit field and integer value, run cap in microusd, and warn percent (1 to 99). Invalid input is shown as an error and nothing is saved. Each save bumps the version as described above.
+
+The editor only uses the standard `select`, `confirm`, and `input` dialogs. It adds no key bindings. Navigation uses the configurable `tui.select.*` bindings (see [keybindings.md](keybindings.md)).
+
+## Selecting a profile for a run
+
+A run selects a profile with `--profile <id>`. If the flag is omitted, the active profile, then `premium`, is used (see Resolution order). The `--profile <id>` flag and the writing of `runs/<id>/admission.json` are NOT part of this change. They are provided by the Flow loader integration (stream A2, pending). B1 provides only `resolveProfile` and `buildCliAdmission`.
+
+`buildCliAdmission` freezes the resolved profile into the admission document for the run:
+
+- The full profile content is embedded, including `{ id, version, digest }`, so later edits to the stored profile do not change a running or recorded run.
+- `spendCapMicrousd` defaults to the profile's `spend.runCapMicrousd`.
+- A spend cap override must be a safe integer from 0 up to `runCapMicrousd`. Otherwise it fails with `spend_cap_exceeded`.
+- `mode` is `direct` for `kind: direct` profiles and `auto` for `kind: flow`.
+- The document gets its own `admissionDigest` and is validated before it is returned.
+
+## Error codes
+
+| Code | Meaning |
+| --- | --- |
+| `profile_not_found` | No profile with that id or path. |
+| `profile_invalid` | Bad id, invalid JSON, failed validation or digest check, id/file-name mismatch, unreadable or non-regular file, or a user profile marked built-in. |
+| `profile_builtin_readonly` | Attempt to save over or delete a built-in profile. |
+| `profile_id_reserved` | Id belongs to a built-in (import, or a stray file in the user directory). |
+| `profile_locked` | Another writer holds `.store.lock`. |
+| `profile_conflict` | The profile changed on disk since the edit started. |
+| `profile_exists` | Creating or importing a profile whose id already exists (without `--replace`). |
+| `active_profile_invalid` | The active pointer is malformed or names a profile that cannot load. |
+| `profile_too_large` | File exceeds 256 KiB. |
+| `store_readonly` | No agent flow directory is configured, so the store cannot be written. |
+| `store_unsafe` | A store directory is a symlink, foreign-owned, or group/world-writable, or the version watermark is unreadable or invalid. |
+| `spend_cap_exceeded` | Spend cap override is not an integer in 0 to `runCapMicrousd`. |
+
+## Telemetry
+
+Flow telemetry events contain no free text: only ids, digests, enum values, and timestamps (see the contracts package `docs/flow-contracts.md`). Profile `label` and `description` are display text and are never emitted in telemetry. Profile ids are emitted, so do not put secrets or user text in an id.
+
+See [Flow profiles: admin reference](../../flow/docs/profiles.md) for built-in model tables, storage, and validation details.

package/docs/flow.md

@@ -0,0 +1,112 @@
+# Flow
+
+Flow is the hierarchical agent harness built into HUMAIN Code. `/flow <goal>` plans a task, dispatches child agents (scouts, leads, workers, reviewers, QA), verifies the result, and reports it. This guide describes what is implemented in this checkout. Items that are not implemented are tagged `(planned)` with the plan section that covers them (the Flow harness implementation plan, streams A1, A2, A3, C1).
+
+## Flow versus direct prompts
+
+A plain prompt goes to the normal session and never touches Flow. Flow runs only when you invoke one of its commands. Flow code is not loaded at startup: HUMAIN Code registers lightweight stub commands plus the `--profile` flag, and the first stub invocation performs one memoized dynamic import of the bundled Flow package. A failed load is reported as `Failed to load Flow: <message>` and is retried on the next invocation.
+
+Stub commands: `/flow`, `/flow-continue`, `/flow-status`, `/flow-cancel`, `/flow-pause`, `/flow-resume`, `/flow-title`, `/flow-models`, `/flow-profile`, `/omsg`.
+
+## `/flow <goal>`
+
+```
+/flow <goal> [--task-class T] [--complexity N] [--risk low|medium|high|critical]
+             [--profile NAME] [--lead-size small|standard|large]
+             [--workflow direct|checked|led|full]
+             [--cheap ALIAS] [--mid ALIAS] [--premium ALIAS] [--frontier ALIAS]
+             [--model <capability>=ALIAS] [--effort LEVEL]
+             [--quality-floor F] [--cost-aggressiveness C] [--max-retries R]
+             [--context FILE ...] [--with-last-reply] [--force]
+```
+
+Flags are honored only before or after the goal text. A `--flag` between goal words is part of the goal. Unrecognized flags are reported, not silently dropped. Values are not all validated by the parser: `--complexity` is rounded and clamped to 1-10, and a non-numeric value falls back to 5. `--risk` and `--task-class` are stored as given, and the parser does not check them against a list of allowed values. The parser also accepts other flags (`--fan-out`, `--candidate`, `--route-only`, `--live-qa`, `--no-live-qa`, `--live-qa-adapter`, `--live-qa-scope`, `--live-qa-acceptance`, `--check`); this guide covers only the flags above.
+
+Auto mode:
+
+- With no triage flags, an LLM triage call fills in task class, complexity, and risk from the goal. The triage model is the first available binding of `implementation_fast`, `worker`, `scout`, then the first adapter binding; it is not chosen by price. If triage fails or no model is dispatchable, the defaults remain (`src/extension.ts:2176-2192,2341`).
+- There is no approval step. Runs auto-approve by default. `--yes` and `-y` are accepted as no-ops.
+- The command parses flags and starts the run in the background; the command handler returns while the run continues. Triage and workflow signal collection run inside the run, so the first dispatch is not instant.
+
+## Sizes and workflows
+
+Flow has four workflow levels: `direct`, `checked`, `led`, `full`.
+
+| Size | Workflow | Meaning |
+|---|---|---|
+| small | `checked` | one implementer plus deterministic repo checks |
+| medium | `led` | lead plus workers, review, QA |
+| large | `full` | architect, recon, several leads, review, QA |
+
+The mapping is implemented as a pure function (`sizeToWorkflow`), and a rules-then-triage size decision exists (`decideSize`: rule classifier first, triage only when rules say medium or large). **Neither is called by the `/flow` run path yet.** Wiring size-based auto mode into `/flow` is `(planned)` (plan section 3 A3, deliverable 3; A2).
+
+What `/flow` does today to pick a level:
+
+- A router reads repository evidence: risk path globs, interface changes across packages, candidate file count, nearby tests, and discovered checks. High risk or a protected path forces `full`. Wide scope or unresolved scope gives `led`. A single localized low-risk file with tests gives `direct`. Otherwise `checked`.
+- The workflow mode controls how much of this applies: `off` (no routing), `observe` (default in `method.json`; plans and records, runs lead/full hierarchy), `enforce` (also runs the flat `direct`/`checked` path). Show or persist it with `/flow-models workflow [off|observe|enforce|default]`. The env var `HUMAIN_ORCHESTRATOR_WORKFLOW_MODE` overrides the saved setting.
+- `--workflow <level>` overrides the routed level, but never below the hard floor; a lower request is rejected and recorded.
+- `--lead-size small|standard|large` sets the lead size directly. Otherwise lead size comes from triage complexity and risk.
+
+### Size override
+
+A user-facing `--size small|medium|large` flag does not exist. The engine-level equivalent today is `--workflow`. A `--size` override is `(planned)` (plan section 3 A3 deliverable 3; section 3 D2 deliverable 1).
+
+### Escalation
+
+- A fresh flat run (`direct`/`checked`) can escalate once to `led` when progress-aware repair requests escalation and retry budget remains. Prior work and failure evidence carry forward. An escalated re-run is never escalated flat again. This only applies in `enforce` mode, because flat runs happen only there.
+- Escalation is not guaranteed. Provider failures, unsafe or unverified scope, blocked work, a read-only task, and an exhausted or explicit retry budget can stop the run without escalation (`src/pipeline/run-orchestration.ts:3090-3137,3351-3365`; `src/pipeline/repair-policy.ts:130-144`).
+- On verification failure, retry leads can move up one lead capability tier.
+- Escalation from medium to large as a size transition, with an `escalated` telemetry event, is `(planned)` (plan section 3 A2, deliverable 12; section 4.3).
+
+## `--profile`
+
+`hc --profile <id>` registers a string flag. When `/flow` runs, it validates the id against `^[a-z0-9][a-z0-9_.:-]{0,127}$` and uses it unless `/flow` itself carried `--profile`. An invalid id is rejected with an error.
+
+Today the id selects a profile in `orchestrator-profiles.json` (model bindings per tier and capability). Precedence for models is: flags, then profile, then the cost-tier resolver. An id not defined in that file produces a warning. Manage these with `/flow-models`.
+
+The versioned Flow profile store and the frozen run admission (`resolveProfile`, `buildCliAdmission`) exist in the Flow package but are not called by the `/flow` run path. Selecting them with `--profile`, and writing `admission.json` for each run, is `(planned)` (plan section 3 A2 deliverables 6 and 9; section 3 B1 deliverable 5). See [flow-profiles.md](flow-profiles.md). `hc --flow-admission <file>` is a string startup flag; it is authoritative for every `/flow` in the session: `/flow --profile` and `/flow --flow-admission <other file>` are refused before dispatch, and the same path is allowed.
+
+## Run control and inspection
+
+| Command | Behavior |
+|---|---|
+| `/flow-status` | Opens the live orchestration board (TUI only; Esc closes it without cancelling the run). Outside the TUI it points to the `orchestrator_status` tool. Reports "No orchestrator run is active." when idle. |
+| `/flow-cancel` | Cancels the active run (reason `user`). Reports "no active run" when idle. |
+| `/flow-title <title>` | Renames the active flow and shows the title on the widget border. Errors with "no active run" when idle. |
+| `/flow-continue [run-id]` | Previews recovery of an interrupted run in its original checkout and asks for explicit confirmation. TUI only. There is no `--yes` or `--force`. With several candidates it lists them and requires an explicit run id. It blocks when ownership, bindings, or process-lineage evidence is unsafe, and asks you to confirm each unresolved external effect. |
+| `/flow-models <sub>` | Subcommands: `show`, `list`, `validate [--live]`, `check`, `set`, `effort`, `use`, `new`, `pick`, `workflow`. Aliases such as `fable-5-1`, `opus-5-5`, `sonnet-5`, `gpt-6-sol`, `gpt-6-luna`, `astra` resolve against your configured models. |
+| `/flow-profile` | Registered as a stub only. The Flow package exports a command implementation, but it is not registered, so the stub answers `/flow-profile is not available yet`. Registering it is `(planned)` (plan section 3 B1, deliverables 3 and 4). |
+
+### Pause and resume `(planned)`
+
+`/flow-pause` and `/flow-resume` are loader stubs with no Flow implementation. Invoking them after Flow loads prints `/flow-pause is not available yet` (or `/flow-resume ...`). Planned semantics (plan section 3 A2 deliverables 7 and 8; section 4.4): stop new dispatch, let running children finish their current turn, then hold until resume. Run-control contracts exist in `packages/humain-code-contracts/src/flow-control.ts`. The runtime control handlers (`flow_pause`, `flow_resume`, `flow_status`, `flow_cancel`, `flow_message`) and the `packages/flow/src/control/` module do not exist in this checkout and are `(planned)`.
+
+### Mid-run messages: `/omsg <text>`
+
+`/omsg` queues a message for the running run. The message is appended to the prompt of the next dispatched task. It is not injected into a running child, because children run without a stdin channel. A literal `\n` becomes a newline. Messages are truncated to a length cap, and the oldest message is dropped when the queue is full. With no active run it warns and does nothing.
+
+Live delivery to the running lead, with queued delivery only in direct mode, is `(planned)` (plan section 3 A2 deliverable 7; section 4.4). Today `/omsg` is always queued.
+
+## Kill switch
+
+Flow can be disabled without affecting direct prompts. Either of these makes every Flow command answer `Flow disabled (<reason>). /<command> is unavailable.` before anything loads:
+
+- Environment variable `HUMAIN_TERMINAL_FLOW_DISABLED` set to `1` or `true` (case-insensitive, trimmed).
+- Setting `flow.enabled` set to `false` in `settings.json`.
+
+Plain prompts do not go through Flow, so they keep working.
+
+## Failure handling
+
+- Terminal outcomes are `completed`, `failed`, or `cancelled`. A failed run is reported as a terminal notification with a title and reason text (for example "Orchestration needs attention" or "Orchestration crashed"). Each lead report carries a status of `completed`, `partial`, `blocked`, or `unknown` (parsed from its `STATUS:` line). The aggregate run outcome is separate: `blocked`, `dispatched`, or `failed`. It is `failed` when there are no leads or no lead exited cleanly, and `blocked` only when every lead exits cleanly and reports `blocked` (`src/run-outcome.ts:18-27,48-66`).
+- Flow does not re-run a failed `/flow` as a direct prompt. I found no such code path, so a failed run is reported, not hidden.
+- After a failed fresh CLI run, Flow shows the failure class (for example `Flow run failed (crash)`) and offers "Retry as Flow" or "Retry direct" through a select. Dismissing the select does nothing. There is no offer for cancelled, `budget_stop`, recovered (`/flow-continue`) or `--flow-admission` runs. "Retry as Flow" respects the kill switch and starts a new run; "Retry direct" sends the goal as a normal prompt.
+- Contracts for the typed settlement fields (`run_settled`, `failureClass`, `retryOffer`) exist in `packages/humain-code-contracts/src/flow-events.ts`. The spend cap enforced from an admission is `(planned)` (plan sections 3 C1, 4.3).
+- Spend limits today: the per-dispatch cap in `method.json` (`dispatch_spend_cap`, default mode `warn`), and the run cancellation when reported plus estimated spend exceeds `SENTINEL_CHILD_MAX_COST_USD` from a HUMAIN Sentinel parent (`packages/flow/src/extension.ts:1155-1163`).
+
+## Related
+
+- [flow-profiles.md](flow-profiles.md)
+- [Flow profiles reference](../../flow/docs/profiles.md)
+- [Known limits](../../flow/docs/known-limits.md)
+- [Migration](../../flow/docs/migration.md)

package/docs/index.md

@@ -41,6 +41,8 @@ HUMAIN Code CLI's tools and extensions run with the permissions of the HUMAIN Co
 ## HUMAIN Code CLI integrations
 
 - [HUMAIN Code CLI](humain-code.md) - branded command names, bundled web access/MCP integration, HUMAIN Node, and Forge/DeployNow setup.
+- [Run Flow](flow.md) - hierarchical Flow runs with `/flow`, run controls, and limits.
+- [Configure Flow Profiles](flow-profiles.md) - Flow profile models, limits, and spend caps.
 - [Agent activity traces](trace.md) - proposal: record, upload and review what an agent did during a run.
 - [HUMAIN Code / Forge Architecture](humain-code-forge-architecture.md) - architecture principles and layer ownership.
 - [HUMAIN Code / Forge Flow Walkthrough](humain-code-forge-flow-walkthrough.md) - current startup and provider-binding data flow.

package/npm-shrinkwrap.json

@@ -1,15 +1,15 @@
 {
 	"name": "@humain/humain-code",
-	"version": "0.3.8",
+	"version": "0.4.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@humain/humain-code",
-			"version": "0.3.8",
+			"version": "0.4.1",
 			"license": "MIT",
 			"dependencies": {
-				"@humain/humain-code-contracts": "0.3.3",
+				"@humain/humain-code-contracts": "0.4.1",
 				"@aws-sdk/client-bedrock-runtime": "3.1146.0",
 				"@earendil-works/pi-agent-core": "1.1.0",
 				"@earendil-works/pi-ai": "1.1.0",
@@ -1024,9 +1024,9 @@
 			"hasInstallScript": true
 		},
 		"node_modules/@humain/humain-code-contracts": {
-			"version": "0.3.3",
-			"resolved": "https://registry.npmjs.org/@humain/humain-code-contracts/-/humain-code-contracts-0.3.3.tgz",
-			"integrity": "sha512-20VmH2kTBufCACOXIKCsJ1a06aA7s03eCYpZDr5L6nq5sq7EuWZ8GXq01AHDsdKl1Oc+MNKaOQxKO0HMI7K+1Q==",
+			"version": "0.4.1",
+			"resolved": "https://registry.npmjs.org/@humain/humain-code-contracts/-/humain-code-contracts-0.4.1.tgz",
+			"integrity": "sha512-a1t8577LgoOeHnU/uND3VMfzVG7f+ClYLqNKYIT44NpDKFirMKEQ7UolKyDPmF6bfHHvrl6dZXDOHcEsZbNYJA==",
 			"license": "MIT",
 			"dependencies": {
 				"typebox": "1.3.35"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@humain/humain-code",
-	"version": "0.3.8",
+	"version": "0.4.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"humainTerminalConfig": {
@@ -76,17 +76,17 @@
 	],
 	"scripts": {
 		"clean": "shx rm -rf dist",
-		"build": "npm run build:unbundled && node ../../scripts/build-coding-agent-bundle.mjs",
+		"build": "npm run build:unbundled && npm --prefix ../flow run build && node ../../scripts/build-coding-agent-bundle.mjs",
 		"build:unbundled": "tsc -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
-		"build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm --prefix ../protocol run build && npm --prefix ../client run build && npm run build && bun build --compile --no-compile-autoload-bunfig --no-compile-autoload-dotenv ./src/bun/cli.ts ./src/utils/image-resize-worker.ts ./src/extensions/codemode/worker.ts --outfile dist/pi && npm run copy-binary-assets",
+		"build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm --prefix ../protocol run build && npm --prefix ../client run build && npm --prefix ../humain-code-contracts run build && npm run build && bun build --compile --no-compile-autoload-bunfig --no-compile-autoload-dotenv ./src/bun/cli.ts ./src/utils/image-resize-worker.ts ./src/extensions/codemode/worker.ts --outfile dist/pi && npm run copy-binary-assets",
 		"copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/ && shx mkdir -p dist/humain/bedrock-provider/vendor && shx cp -r src/humain/bedrock-provider/vendor/* dist/humain/bedrock-provider/vendor/",
-		"copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/ && shx mkdir -p dist/humain-modules/ponytail dist/humain-modules/caveman && shx cp -r src/humain/ponytail/vendor/skills src/humain/ponytail/vendor/LICENSE dist/humain-modules/ponytail/ && shx cp -r src/humain/caveman/vendor/skills src/humain/caveman/vendor/LICENSE src/humain/caveman/vendor/LICENSE-MIT src/humain/caveman/vendor/NOTICE dist/humain-modules/caveman/ && shx mkdir -p dist/humain-modules/adhd && shx cp -r src/humain/adhd/vendor/skills src/humain/adhd/vendor/LICENSE dist/humain-modules/adhd/ && shx mkdir -p dist/humain-modules/coordination && shx cp src/coordination/vendor/LICENSE dist/humain-modules/coordination/",
+		"copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/ && shx mkdir -p dist/humain-modules/ponytail dist/humain-modules/caveman && shx cp -r src/humain/ponytail/vendor/skills src/humain/ponytail/vendor/LICENSE dist/humain-modules/ponytail/ && shx cp -r src/humain/caveman/vendor/skills src/humain/caveman/vendor/LICENSE src/humain/caveman/vendor/LICENSE-MIT src/humain/caveman/vendor/NOTICE dist/humain-modules/caveman/ && shx mkdir -p dist/humain-modules/adhd && shx cp -r src/humain/adhd/vendor/skills src/humain/adhd/vendor/LICENSE dist/humain-modules/adhd/ && shx mkdir -p dist/humain-modules/coordination && shx cp src/coordination/vendor/LICENSE dist/humain-modules/coordination/ && shx mkdir -p dist/flow && shx cp -r ../flow/agents ../flow/assets ../flow/package.json dist/flow/",
 		"test": "vitest --run",
 		"shrinkwrap": "node ../../scripts/generate-coding-agent-shrinkwrap.mjs",
 		"prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap"
 	},
 	"dependencies": {
-		"@humain/humain-code-contracts": "0.3.3",
+		"@humain/humain-code-contracts": "0.4.1",
 		"@aws-sdk/client-bedrock-runtime": "3.1146.0",
 		"@earendil-works/pi-agent-core": "1.1.0",
 		"@earendil-works/pi-ai": "1.1.0",
@@ -135,6 +135,7 @@
 		"@mariozechner/clipboard": "0.3.9"
 	},
 	"devDependencies": {
+		"@humain/flow": "0.4.0-flow.0",
 		"@types/cross-spawn": "6.0.6",
 		"@types/diff": "8.0.0",
 		"@types/hosted-git-info": "3.0.5",