@lazyingart/agintiflow 0.20.49 → 0.20.50

package/references/aaps-agintiflow-integration-design.md

@@ -0,0 +1,710 @@
+# AAPS And AgInTiFlow Integration Design
+
+This note researches how AgInTiFlow should connect with AAPS and proposes a lightweight `/aaps` feature that can grow into a full large-project workflow harness.
+
+Local sources inspected:
+
+- `/home/lachlan/ProjectsLFS/AAPS/package.json`
+- `/home/lachlan/ProjectsLFS/AAPS/README.md`
+- `/home/lachlan/ProjectsLFS/AAPS/docs/design-philosophy.md`
+- `/home/lachlan/ProjectsLFS/AAPS/docs/language-spec.md`
+- `/home/lachlan/ProjectsLFS/AAPS/docs/compiler.md`
+- `/home/lachlan/ProjectsLFS/AAPS/docs/runtime.md`
+- `/home/lachlan/ProjectsLFS/AAPS/docs/project-management.md`
+- `/home/lachlan/ProjectsLFS/AAPS/docs/codex-wrapper.md`
+- `/home/lachlan/ProjectsLFS/AAPS/scripts/aaps.js`
+- `/home/lachlan/ProjectsLFS/AAPS/scripts/aaps-runner.js`
+- `/home/lachlan/ProjectsLFS/AAPS/scripts/aaps-compiler.js`
+- `/home/lachlan/ProjectsLFS/AAPS/examples/*.aaps`
+- `/home/lachlan/ProjectsLFS/AAPS/examples/projects/app-development/aaps.project.json`
+- AgInTiFlow runtime, CLI, web, task profiles, skill library, session store, canvas/artifact tunnel, SCS mode, and wrapper architecture.
+
+## Short Answer
+
+Yes, AAPS can lift AgInTiFlow to the next level, but the integration should be deliberately thin at first.
+
+Recommended principle:
+
+> AAPS is the declarative large-workflow control plane. AgInTiFlow is the interactive agent runtime and tool-use backend.
+
+Do not merge the projects or copy the AAPS parser into AgInTiFlow. Use the published `@lazyingart/aaps` package as an optional dependency discovered at runtime, then wrap it with a stable AgInTiFlow adapter.
+
+The first useful feature should be:
+
+```text
+/aaps
+/aaps status
+/aaps init
+/aaps parse|validate|compile|check|run
+/aaps open
+/aaps studio
+/aaps install
+```
+
+Later:
+
+```text
+/aaps on
+/aaps auto
+/aaps off
+```
+
+Those mode commands should not mean "turn AgInTi into AAPS." They should mean "when a task is large, ask AgInTi to express the work as AAPS blocks, compile/check it, and then execute or supervise the blocks."
+
+## Current AAPS Shape
+
+AAPS means Autonomous Agentic Pipeline Script. The current local package is `@lazyingart/aaps` and exposes the `aaps` CLI.
+
+Important properties:
+
+- It is CommonJS, Node >=18.
+- It has a deterministic parser in `src/aaps.js`.
+- It has a CLI front door in `scripts/aaps.js`.
+- It has an agent-aware compiler in `scripts/aaps-compiler.js`.
+- It has an executable runtime in `scripts/aaps-runner.js`.
+- It has a Studio PWA and Python backend in `studio/` and `backend/`.
+- It has schemas for chat/edit/project/response payloads.
+- It already supports project manifests through `aaps.project.json`.
+- It already has example workflows for app development, book writing, generic workflows, runtime demos, and organoid segmentation.
+
+AAPS pipeline:
+
+```text
+.aaps
+-> deterministic parser
+-> unresolved IR
+-> compiler
+-> resolved IR
+-> execution plan
+-> readiness check
+-> runtime actions
+-> validation/recovery/report
+```
+
+The useful design boundary is strict:
+
+- Parse does not invent missing code.
+- Compile can detect missing blocks/scripts/tools/agents/packages and optionally generate safe project-local assets.
+- Run executes deterministic local actions and records prompt/model-only work as prompts/checkpoints unless an adapter exists.
+- Every run writes durable JSON, JSONL, reports, readiness, logs, and artifacts.
+
+## Current AgInTiFlow Shape
+
+AgInTiFlow already owns the runtime pieces AAPS wants from a backend agent:
+
+- Role-based model routing: route/main/spare/wrapper/auxiliary.
+- CLI and local web UI over the same session store.
+- Central session storage under `~/.agintiflow/sessions/<session-id>`.
+- Project session pointers under `.aginti-sessions/`.
+- Workspace file tools with path guardrails.
+- Docker workspace and command policy.
+- Host tmux tools for long-running jobs.
+- Browser, web search, canvas/artifact tunnel, and generated file previews.
+- Task profiles and Markdown skills, including an existing `aaps` profile/skill.
+- Optional SCS mode for plan approval, progress monitoring, and finish gates.
+- Wrapper tools for external coding assistants.
+- Structured `events.jsonl` for every model/tool/session event.
+
+AgInTiFlow current execution loop:
+
+```text
+goal
+-> resolve runtime config and model route
+-> create/resume session
+-> plan
+-> optional scouts/SCS
+-> model tool loop
+-> guarded tools
+-> events/artifacts/chat
+-> finish/resume
+```
+
+This is complementary to AAPS. AAPS is better at declared workflow shape. AgInTiFlow is better at interactive environment-facing agent work.
+
+## What AAPS Adds To AgInTiFlow
+
+AAPS gives AgInTiFlow a better language for large tasks:
+
+- Named workflows instead of transient chat plans.
+- Reusable `skill`, `block`, `task`, `stage`, `action`, `guard`, `choose`, `if`, `else`, and `for_each` blocks.
+- Typed inputs, outputs, artifacts, validations, requirements, agents, tools, and environment declarations.
+- Readiness checks before side effects.
+- Compile reports for missing scripts/tools/agents/packages.
+- Project manifests for multi-file workflow libraries.
+- A visual editor and graph-shaped mental model.
+- Durable run/report folders independent of the chat transcript.
+
+This solves a real weakness of ordinary agents: they make plans as prose, then the plan decays as execution gets messy. AAPS turns large-task plans into editable source.
+
+## What AgInTiFlow Adds To AAPS
+
+AgInTiFlow gives AAPS a stronger backend:
+
+- Real browser/workspace/shell/canvas tooling.
+- Better model-provider control, including DeepSeek/Venice/OpenAI/Qwen.
+- Project-local API key onboarding.
+- Docker workspace policy.
+- tmux supervision.
+- Session history and resumability.
+- Web app workspace controls and artifact previews.
+- SCS monitoring and finish gates.
+- Skill Mesh and learned capability sharing later.
+
+This solves a current AAPS limitation: AAPS can prepare prompts and run deterministic actions, but agent-assisted blocks currently depend on Codex wrapper or prompt files. AgInTiFlow can become a first-class AAPS agent adapter.
+
+## Integration Options
+
+### Option A: Shell Adapter To `aaps` CLI
+
+AgInTiFlow discovers `aaps` on `PATH` or runs `npx -y @lazyingart/aaps`.
+
+Pros:
+
+- Minimal implementation.
+- No dependency bloat in AgInTiFlow.
+- Uses the actual published AAPS package.
+- Easy to debug because commands are visible.
+- Works with current AAPS immediately.
+
+Cons:
+
+- JSON parsing and error mapping must be careful.
+- Version mismatch is possible.
+- Shell command policy must explicitly allow safe AAPS commands.
+- Web UI integration needs a wrapper API.
+
+Verdict: best first step.
+
+### Option B: Optional Dynamic Package Import
+
+AgInTiFlow dynamically imports `@lazyingart/aaps` if installed.
+
+Pros:
+
+- Faster than spawning CLI.
+- Cleaner API if AAPS exports parser/compiler functions.
+- Easier web preview of IR.
+
+Cons:
+
+- AAPS is currently CommonJS and CLI-oriented.
+- Compiler/runner are script-level, not stable library APIs.
+- Pulls optional package complexity into AgInTiFlow.
+
+Verdict: good later after AAPS exposes stable library exports.
+
+### Option C: Vendored/Submodule Integration
+
+AgInTiFlow vendors AAPS or uses the local sibling path.
+
+Pros:
+
+- Easy local development.
+- Exact source is available.
+
+Cons:
+
+- Bad product boundary.
+- Hard to maintain.
+- Increases npm package size.
+- Risks copying dirty local state.
+
+Verdict: avoid for product runtime. Use only for local development references.
+
+### Option D: AAPS Runtime Calls AgInTiFlow API
+
+AAPS agent registry gets an `agintiflow` invocation that starts/resumes AgInTiFlow runs through API calls.
+
+Pros:
+
+- Correct long-term architecture.
+- AAPS remains the declarative control plane.
+- AgInTiFlow becomes the backend agent for specific blocks.
+- AAPS Studio can display AgInTiFlow session and artifact links.
+
+Cons:
+
+- Requires stable AgInTiFlow run API and event streaming.
+- Requires careful permission mapping.
+- Requires cancellation/resume semantics.
+- Needs a clear project/session identity bridge.
+
+Verdict: best long-term bridge after the lightweight AgInTi-side adapter works.
+
+## Recommended Architecture
+
+Implement a new AgInTiFlow module:
+
+```text
+src/aaps-adapter.js
+```
+
+Responsibilities:
+
+- Detect whether AAPS is available.
+- Resolve the AAPS executable command:
+  - `AAPS_BIN`
+  - `node <local-sibling>/scripts/aaps.js` for development when allowed
+  - `aaps` on PATH
+  - `npx -y @lazyingart/aaps` only when install/network policy allows
+- Run safe AAPS commands with project-relative paths.
+- Parse JSON output and normalize errors.
+- Summarize AAPS project status.
+- Find `aaps.project.json`.
+- Find active/default `.aaps` workflow.
+- Return artifact paths and run/compile directories.
+- Never read or print `.env` values.
+
+Adapter surface:
+
+```js
+detectAaps({ cwd })
+ensureAaps({ cwd, installPolicy })
+initAapsProject({ cwd, name, domain, mode })
+listAapsFiles({ cwd })
+parseAaps({ cwd, file })
+validateAaps({ cwd, file })
+compileAaps({ cwd, file, mode })
+checkAaps({ cwd, file })
+runAaps({ cwd, file, dryRun, block })
+openAapsStudio({ cwd, host, port, tmux })
+summarizeAapsArtifacts({ cwd, report })
+```
+
+Use `run_command` policy only for the implementation, not raw LLM shell guessing. The model should request an explicit `aaps_*` tool once the adapter graduates from slash command to model tool.
+
+## Slash Command Design
+
+Interactive CLI:
+
+```text
+/aaps
+/aaps status
+/aaps install
+/aaps init [name]
+/aaps files
+/aaps open [file]
+/aaps parse [file]
+/aaps validate [file]
+/aaps compile [file] [check|suggest|apply]
+/aaps check [file]
+/aaps run [file]
+/aaps dry-run [file]
+/aaps studio
+/aaps on
+/aaps auto
+/aaps off
+```
+
+Default `/aaps` behavior:
+
+1. If no AAPS project exists, show a compact explainer plus options:
+   - initialize project
+   - create first workflow from current goal
+   - install/find AAPS
+2. If an AAPS project exists, show:
+   - project name/domain
+   - active file
+   - available workflows
+   - last compile/run status
+   - suggested next commands
+
+State fields:
+
+```js
+state.enableAaps = "off" | "on" | "auto"
+state.aapsFile = ""
+state.aapsProjectRoot = state.commandCwd
+state.aapsCompileMode = "check" | "suggest" | "apply"
+```
+
+CLI flags:
+
+```text
+--aaps
+--aaps auto
+--no-aaps
+--aaps-file workflows/main.aaps
+```
+
+## Web UI Design
+
+Do not put AAPS into the left daily settings column at first. It is too large.
+
+Add an **AAPS** panel/tab in the workspace area:
+
+- Project status card.
+- Active `.aaps` workflow selector.
+- Source editor.
+- Parse diagnostics.
+- IR/graph preview.
+- Compile/check/run buttons.
+- Missing components list.
+- Generated setup prompts and agent prompts.
+- Run reports and artifacts.
+- Button to send selected report/artifact to canvas.
+
+Use existing Canvas & Artifacts for outputs rather than building a second preview system.
+
+Suggested web layout:
+
+```text
+Left: normal AgInTi controls
+Center: chat/session
+Right/lower workspace tabs:
+  Logs
+  Workspace files
+  Canvas
+  AAPS
+  Sandbox
+```
+
+AAPS editor should use the existing guarded file APIs at first. Later it can reuse AAPS Studio components or import AAPS parser directly in the browser.
+
+## Model Behavior With AAPS Mode
+
+When `/aaps on` or `/aaps auto` is enabled, the prompt should change:
+
+- For large ambiguous tasks, first propose or update an AAPS workflow.
+- Use `.aaps` as the durable high-level plan.
+- Compile/check before running.
+- Use AgInTiFlow tools to implement missing scripts/assets only when compile reports require them.
+- Keep all generated assets project-local.
+- Use SCS for risky large tasks automatically.
+- Publish final report/artifacts through canvas.
+
+Auto activation signals:
+
+- User asks for "large project", "pipeline", "workflow", "autonomous", "repeatable", "batch", "analysis", "book", "paper", "app review", "multi-step".
+- The task needs many phases or repeated loops.
+- The task has clear inputs/outputs/artifacts.
+- The task should be reused later.
+- The project contains `aaps.project.json` or `.aaps` files.
+
+Avoid AAPS mode for:
+
+- one-off shell/file questions;
+- tiny edits;
+- normal code review;
+- tasks where a short direct tool loop is cheaper and clearer.
+
+## AAPS As Backend Agent Consumer
+
+Long-term, AAPS should be able to declare an AgInTiFlow agent:
+
+```json
+{
+  "name": "agintiflow_main",
+  "invocation": "agintiflow",
+  "provider": "deepseek",
+  "modelRole": "main",
+  "sandboxMode": "docker-workspace",
+  "packageInstallPolicy": "allow",
+  "tools": ["files", "shell", "browser", "canvas"]
+}
+```
+
+AAPS `exec agent "agintiflow_main"` would call an AgInTiFlow service:
+
+```text
+POST /api/agent-runs
+GET  /api/agent-runs/:id
+GET  /api/agent-runs/:id/events
+POST /api/agent-runs/:id/inbox
+POST /api/agent-runs/:id/stop
+```
+
+The payload should include:
+
+```json
+{
+  "projectRoot": "/path/to/aaps/project",
+  "commandCwd": "/path/to/aaps/project",
+  "goal": "Execute AAPS block qc_image with these inputs and outputs.",
+  "aaps": {
+    "project": "aaps.project.json",
+    "workflow": "workflows/main.aaps",
+    "block": "qc_image",
+    "runId": "aaps-run-123",
+    "contract": {
+      "inputs": [],
+      "outputs": [],
+      "validations": [],
+      "stopConditions": []
+    }
+  },
+  "policy": {
+    "sandboxMode": "docker-workspace",
+    "packageInstallPolicy": "allow",
+    "allowDestructive": false
+  }
+}
+```
+
+AgInTiFlow returns:
+
+```json
+{
+  "sessionId": "web-agent-...",
+  "status": "finished",
+  "result": "...",
+  "artifacts": [],
+  "eventsPath": "~/.agintiflow/sessions/.../events.jsonl",
+  "changedFiles": [],
+  "checks": []
+}
+```
+
+AAPS can then write those links into its run report.
+
+## Mapping AAPS Contracts To AgInTiFlow
+
+| AAPS concept | AgInTiFlow mapping |
+| --- | --- |
+| `pipeline` | session goal plus optional AAPS project metadata |
+| `agent` | model role/provider plus tool permissions |
+| `skill` / `block` | AgInTi skill prompt plus tool contract |
+| `task` | one run phase or queued prompt |
+| `stage` | SCS phase or log section |
+| `action run/exec` | guarded shell/file/browser tool call |
+| `validate` / `verify` | explicit checks before `finish` |
+| `guard` | SCS student gate plus runtime policy |
+| `recover` / `fallback` | retry/fallback prompt injected after failure |
+| `artifact` / `output` | workspace file plus `send_to_canvas` |
+| `events.jsonl` | AgInTiFlow session events plus AAPS run events |
+| `run.json` | AgInTiFlow session pointer plus AAPS run summary |
+
+## Safety Model
+
+AAPS integration must not become a backdoor around AgInTiFlow policy.
+
+Rules:
+
+- AAPS commands run inside the current `commandCwd` or an explicitly chosen AAPS project root.
+- All AAPS file arguments must be project-relative.
+- No absolute paths, `..`, home paths, `.env`, `.git`, `node_modules`, or secret-like paths in generated commands.
+- `aaps compile --mode apply` is a write action and should require normal workspace-write policy.
+- `aaps run` may execute workflow commands; route it through existing shell/Docker policy.
+- `aaps studio` should start in host tmux or a durable process, not a short Docker command.
+- `npx -y @lazyingart/aaps` requires package/network install policy.
+- `aaps install` should be explicit. Auto-install can offer a selector, not silently install.
+- All AAPS run/compile artifacts should be captured as session artifacts or canvas links.
+- Never share AAPS project files through Skill Mesh unless the user explicitly exports a sanitized skill pack.
+
+## Storage Model
+
+Keep AAPS project files in the project:
+
+```text
+aaps.project.json
+workflows/
+blocks/
+skills/
+scripts/
+tools/
+agents/
+artifacts/
+runs/
+reports/
+notes/
+```
+
+Keep AgInTi session metadata in AgInTi storage:
+
+```text
+~/.agintiflow/sessions/<session-id>/
+.aginti-sessions/<session-id>/session.json
+```
+
+Bridge with pointers:
+
+```json
+{
+  "sessionId": "web-agent-...",
+  "aapsProjectRoot": "/path/project",
+  "aapsWorkflow": "workflows/main.aaps",
+  "aapsRunDir": "runs/20260504_run",
+  "aapsCompileDir": "runs/20260504_compile"
+}
+```
+
+Do not move AAPS run directories into `~/.agintiflow`. AAPS artifacts are part of the project workflow and should remain portable with the AAPS project.
+
+## Installation Strategy
+
+Preferred resolution order:
+
+1. `AAPS_BIN` env var.
+2. Local project dependency: `node_modules/.bin/aaps`.
+3. Global `aaps` on PATH.
+4. Development sibling path `/home/lachlan/ProjectsLFS/AAPS/scripts/aaps.js` only in source checkout/dev mode.
+5. `npx -y @lazyingart/aaps` when package policy allows network/package setup.
+
+First `/aaps install` behavior:
+
+- Explain that AAPS is optional.
+- Show detected status.
+- Offer project-local dev dependency as the default for reproducibility.
+- Global install only if user explicitly asks.
+
+Possible commands:
+
+```bash
+npm install --save-dev @lazyingart/aaps
+npm install -g @lazyingart/aaps
+```
+
+In AgInTiFlow’s own npm package, do not add `@lazyingart/aaps` as a hard dependency initially. Use optional discovery to keep the CLI light.
+
+## How AAPS And SCS Should Work Together
+
+SCS and AAPS solve different layers.
+
+- AAPS: durable workflow specification and block contract.
+- SCS: runtime gatekeeper for plan/phase/progress/finish.
+
+Recommended combined behavior:
+
+- `/aaps auto` implies SCS auto for large AAPS runs.
+- SCS student should judge AAPS compile/readiness/run evidence before finish.
+- AAPS `guard` and `validate` statements should be included in the SCS evidence pack.
+- If AAPS readiness is blocked, SCS should reject finish unless the final answer honestly reports the blocker and points to the setup/repair prompts.
+
+Do not use both AAPS and parallel scouts by default. AAPS is already a structured planning layer; if extra critique is needed, use SCS or a review block explicitly.
+
+## Minimal First Implementation
+
+Implement only this first:
+
+1. Add `src/aaps-adapter.js`.
+2. Add `/aaps status`, `/aaps install`, `/aaps init`, `/aaps validate`, `/aaps compile`, `/aaps check`, `/aaps run`, `/aaps studio`.
+3. Add CLI flags `--aaps`, `--aaps-file`.
+4. Add a safe AAPS status summary to `/status` when an AAPS project exists.
+5. Add docs and smoke tests with `AAPS_MOCK` or local AAPS examples.
+6. Do not add web editor yet.
+
+First smoke tests:
+
+```bash
+node scripts/smoke-aaps.js
+```
+
+Smoke should cover:
+
+- no AAPS installed -> status returns actionable missing state;
+- sibling AAPS path -> parse example;
+- project with `aaps.project.json` -> validate;
+- compile check -> report path captured;
+- dry-run/check -> no destructive side effects;
+- `/aaps status` works in non-interactive simulation.
+
+## Web Implementation After CLI
+
+After CLI is stable:
+
+1. Add `/api/aaps/status`.
+2. Add `/api/aaps/files`.
+3. Add `/api/aaps/file?path=...`.
+4. Add `/api/aaps/file` save endpoint with guarded path checks.
+5. Add `/api/aaps/parse`.
+6. Add `/api/aaps/compile`.
+7. Add `/api/aaps/run`.
+8. Add AAPS tab in web UI.
+
+The web editor can start as plain textarea plus diagnostics. The graph can come later.
+
+## Product UX
+
+The user mental model should be simple:
+
+```text
+Chat is for working.
+AAPS is for making the work repeatable.
+AgInTi executes.
+AAPS remembers the pipeline.
+```
+
+Example flow:
+
+```text
+user> /aaps init "Android release QA"
+user> make a workflow to build, install, screenshot, inspect logs, and summarize this Android app
+aginti> creates workflows/android_release_qa.aaps
+aginti> runs aaps compile --mode check
+aginti> reports missing emulator/device setup or readiness
+user> /aaps run
+aginti> runs the executable blocks, uses AgInTi tools where needed, publishes screenshots/reports to canvas
+```
+
+## Why This Can Bring AgInTiFlow Up A Level
+
+Normal coding agents are strong at local execution but weak at durable workflow shape.
+
+AAPS gives AgInTiFlow:
+
+- reusable project scripts for repeated work;
+- user-editable high-level workflows;
+- GUI-editable block graphs;
+- compile/readiness reports before side effects;
+- a natural form for large projects, papers, books, app QA, data analysis, and scientific pipelines.
+
+AgInTiFlow gives AAPS:
+
+- a real model/tool runtime;
+- model/provider selection;
+- browser/shell/file/canvas actions;
+- long-running session management;
+- better local UI;
+- safer tool policy.
+
+Together:
+
+```text
+AAPS = source code for autonomous work
+AgInTiFlow = runtime for autonomous work
+```
+
+That is the clean product story.
+
+## Risks
+
+- Too much UI too early can make AgInTiFlow feel heavy.
+- Silent auto-install of AAPS would surprise users.
+- Running AAPS workflows can execute arbitrary declared commands if not routed through policy.
+- Two run stores can confuse users unless linked clearly.
+- If AgInTiFlow starts editing `.aaps` without compiling it, AAPS loses its main value.
+- If AAPS Studio and AgInTi web both become full editors, duplicated UI maintenance will grow.
+
+Mitigation:
+
+- Start CLI-only.
+- Use the AAPS CLI as source of truth.
+- Show compile/run artifacts through existing AgInTi canvas.
+- Add web editor only after adapter events and smoke tests are reliable.
+- Keep install optional.
+
+## Final Recommendation
+
+Implement `/aaps` as a lightweight optional adapter first.
+
+Do not make AAPS a hard dependency of AgInTiFlow. Do not merge the runtimes. Do not start with a full visual editor.
+
+First milestone:
+
+```text
+AgInTiFlow can detect/install AAPS, initialize a project, validate/compile/check/run `.aaps`, and surface reports/artifacts in the current session.
+```
+
+Second milestone:
+
+```text
+AgInTiFlow web can edit `.aaps`, show parse diagnostics, and run compile/check/run from an AAPS tab.
+```
+
+Third milestone:
+
+```text
+AAPS can invoke AgInTiFlow as a backend agent for `exec agent "agintiflow_main"` blocks.
+```
+
+This keeps the architecture elegant: AAPS remains the explicit top-down pipeline language, while AgInTiFlow becomes the practical execution engine and user-facing agent workspace.