@lazyingart/agintiflow 0.20.49 → 0.20.50

package/references/student-committee-supervisor-mode.md

@@ -0,0 +1,331 @@
+# Student-Committee-Supervisor Mode
+
+This note researches the current AgInTiFlow execution pipeline and proposes a standalone `/enabless` mode: Student-Committee-Supervisor, abbreviated `SCS`.
+
+The name intentionally keeps the reversed-role joke: the "student" supervises, the "supervisor" executes, and the "committee" drafts but cannot decide.
+
+## Current Working Pipeline
+
+The current AgInTiFlow runner is a single-executor agent loop with optional advisory scouts.
+
+Current flow:
+
+1. CLI/web state chooses runtime settings: provider, routing mode, role models, task profile, shell/file/web/scout toggles, sandbox, and max steps.
+2. `resolveRuntimeConfig()` selects one effective provider/model for the run using `selectModelRoute()`. The route/main/spare role settings exist, but each run still has one active `config.provider` and `config.model`.
+3. `runAgent()` creates or resumes a central session store, creates an OpenAI-compatible client, loads project instructions, selected skills, profile prompts, engineering guidance, tool policy text, and the user goal into the model context.
+4. If the session has no plan, `createPlan()` asks the active run model to draft a concise 3-6 step plan. This plan is saved and rendered, but it is not independently approved.
+5. If the task is complex and scouts are enabled, `runParallelScouts()` builds a bounded context pack, runs several advisory scout calls, synthesizes a Swarm Board, saves `scout-blackboard.json`, and injects the summary as advisory user context.
+6. The executor loop starts. Each step drains queued user input, captures a browser or synthetic runtime snapshot, appends step state to the conversation, calls `requestNextStep()`, executes any returned tool calls, records events, saves state, and repeats.
+7. Tools are deterministic and policy-guarded: file tools, shell/Docker, tmux, web search, browser, wrapper delegation, image generation, canvas, and `finish`.
+8. Loop guards inject warnings when the same failed/blocked tool call repeats.
+9. The run ends when the model calls `finish`, returns assistant content without tools, hits max steps, or is interrupted.
+10. Housekeeping flushes after the run.
+
+Important current properties:
+
+- Planning and execution use the same active run model.
+- Smart routing decides the active model before the run. It does not currently run planning on route and execution on main as separate inner roles.
+- Parallel scouts are advisory only. They cannot approve, veto, pause, or request replanning.
+- `/review` is implemented as a slash-command prompt wrapper that runs the normal executor in review profile with a bounded review prompt.
+- Session events are already rich enough to support a monitor: `plan.created`, `parallel_scouts.completed`, `model.requested`, `model.responded`, `tool.started`, `tool.completed`, `tool.failed`, `tool.blocked`, `loop.guard`, `file.changed`, `session.finished`, and `session.stopped`.
+
+Relevant implementation files:
+
+- `src/config.js`: runtime config and role-model resolution.
+- `src/model-routing.js`: smart/manual route selection and model catalogs.
+- `src/model-client.js`: plan call, tool schema, text tool-call fallback, next-step request.
+- `src/parallel-scouts.js`: advisory scout swarm and coordinator board.
+- `src/agent-runner.js`: session lifecycle, plan creation, event loop, tool execution, queued input, finish behavior.
+- `src/interactive-cli.js`: slash commands such as `/review`, `/route`, `/model`, `/scouts`, `/skillmesh`.
+
+## Proposed SCS Contract
+
+`/enabless` enables a stricter internal workflow for the current interactive session.
+
+Roles:
+
+| Role | Model | Rights | No-rights boundary |
+| --- | --- | --- | --- |
+| Student | Main model | Monitor execution, approve plan, veto plan, request rethink based on evidence, decide whether enough work was done. | Does not execute tools directly. |
+| Committee | Main model | Draft candidate plans and alternatives. | Cannot approve, veto, replan after execution starts, or call tools. |
+| Supervisor | Main model | Execute the approved plan with the existing tool loop. | Cannot draft its own initial plan, cannot approve its own plan, cannot declare strategic replans without student permission. |
+
+The user asked that once `/enabless` is enabled, all SCS work uses the main model. This is sensible for determinism: no route/main mismatch, no cheap planner producing a plan that a stronger executor dislikes, and no confusing cross-model responsibility. It also makes cost predictable because the feature is opt-in.
+
+## Pros
+
+SCS improves AgInTiFlow in several ways.
+
+- It separates plan quality from tool execution. The current executor can draft a plan then immediately execute it; SCS inserts a real gate.
+- It makes the monitor role explicit. Existing scouts advise before execution, but they do not watch tool results or catch false completion.
+- It turns repeated failure into controlled replanning. Current loop guards warn the executor; SCS lets a separate monitor decide that the current plan is bad.
+- It improves long-running task discipline. A student monitor can check whether acceptance criteria are still aligned after each milestone.
+- It creates a good path for self-supervision. The student role can later become a reusable quality gate across coding, Android, LaTeX, writing, GitHub, system maintenance, and design profiles.
+- It maps well to existing event logs. The runner already records enough state for a monitor to summarize and judge without re-reading the whole transcript.
+- It preserves the existing tool surface. The supervisor can be the same `requestNextStep()` executor with extra constraints.
+- It fits mature agent patterns: Codex-style streaming events and review modes, Qwen-style permission callbacks and plan mode, Claude-style multi-agent review, and Gemini-style behavioral eval feedback.
+
+## Cons And Failure Modes
+
+SCS also has real risks.
+
+- It may slow simple tasks. Three internal roles are wasteful for `ls`, `pwd`, or a short answer.
+- It can create circular authority. If the supervisor cannot propose replans but discovers new facts through tools, the student must translate those facts into a rethink request.
+- It can overfit to plan approval. Many coding tasks need opportunistic discovery; the initial plan should be a phase plan, not a rigid contract.
+- It can produce committee noise. A committee that only drafts plans can still waste tokens if asked too often or without a tight schema.
+- It can reduce model diversity. Using only the main model avoids cross-model confusion but loses cheap scouts and independent failure modes.
+- It can deadlock on veto. A bad student veto could block progress unless there is a bounded retry policy.
+- It can hide accountability if events are not explicit. Every SCS decision must be logged as a typed event with evidence and role.
+- It can degrade UX if the CLI prints every internal debate. Users should see compact state: `SCS plan approved`, `SCS rethink requested`, `SCS vetoed: reason`.
+
+## Recommended Mature Design
+
+The strongest version is not a permanent three-agent debate. It is a gated phase controller with three role prompts and strict event contracts.
+
+Use this model:
+
+1. Committee drafts candidate phase plans.
+2. Student selects, edits, approves, or vetoes one plan.
+3. Supervisor executes only the approved next phase.
+4. Student evaluates evidence after each phase or after a failure trigger.
+5. If accepted, continue to the next phase or finish.
+6. If rejected, student requests committee rethink with evidence.
+
+The key change is "phase", not "whole task". The committee should draft the next 1-3 milestones, not a giant plan for the whole project. This matches the existing rolling autonomy roadmap and avoids brittle long lists.
+
+Decision schema:
+
+```json
+{
+  "role": "student",
+  "decision": "approve_plan | veto_plan | rethink_plan | accept_phase | reject_phase | finish_allowed",
+  "confidence": 0.0,
+  "evidence": ["event ids, file paths, command summaries, tool failures"],
+  "reason": "short concrete reason",
+  "next_required_action": "committee_rethink | supervisor_execute | supervisor_continue | finish"
+}
+```
+
+Committee schema:
+
+```json
+{
+  "role": "committee",
+  "phase_goal": "one concrete milestone",
+  "plan": ["3-6 concrete steps"],
+  "acceptance_criteria": ["observable evidence"],
+  "allowed_tools": ["inspect_project", "search_files", "read_file", "apply_patch", "run_command"],
+  "stop_conditions": ["blocked dependency", "dirty unrelated files", "same failure twice"]
+}
+```
+
+Supervisor constraint:
+
+```text
+Execute only the approved phase plan. You may choose exact tools and paths, but you may not invent a new strategic plan. If tool results invalidate the plan, report the evidence and stop for student review.
+```
+
+## Standalone Feature Architecture
+
+Implement SCS as an optional orchestration layer around the existing runner, not as a rewrite of tools.
+
+New config/state:
+
+- `AGINTI_SCS_MODE=true`
+- CLI flag: `--enable-scs`
+- interactive command: `/enabless`, `/enabless off`, `/enabless status`
+- state fields:
+  - `state.enableScs`
+  - `state.scs.phase`
+  - `state.scs.plan`
+  - `state.scs.studentDecision`
+  - `state.scs.history`
+
+New module:
+
+- `src/scs-controller.js`
+
+Responsibilities:
+
+- Build compact evidence packs from session state and recent events.
+- Ask committee for a phase plan using the main model.
+- Ask student to approve/veto/rethink using the main model.
+- Inject the approved phase plan as a system/user constraint before supervisor execution.
+- Decide when to pause execution and trigger student review.
+- Persist typed SCS events.
+
+Suggested events:
+
+- `scs.enabled`
+- `scs.committee.plan_drafted`
+- `scs.student.plan_approved`
+- `scs.student.plan_vetoed`
+- `scs.student.rethink_requested`
+- `scs.supervisor.phase_started`
+- `scs.supervisor.phase_blocked`
+- `scs.student.phase_accepted`
+- `scs.student.phase_rejected`
+- `scs.finished_allowed`
+
+Execution hooks:
+
+1. Before `createPlan()`: if SCS is enabled, call committee planner instead of normal `createPlan()`.
+2. After committee plan: call student approval. If vetoed, retry committee with veto reason up to a small bound such as 2.
+3. Before each executor request: inject approved phase plan and supervisor constraints.
+4. After each tool failure/block, repeated loop guard, file change batch, or N steps: call student monitor.
+5. Before `finish`: require student `finish_allowed` unless the run is stopped by user/max steps.
+
+This preserves current tool execution while adding a decision layer.
+
+## Trigger Policy
+
+Do not run SCS on every task unless the user explicitly enables it.
+
+Recommended modes:
+
+| Mode | Behavior |
+| --- | --- |
+| `off` | Current behavior. |
+| `on` | SCS gates all non-trivial work in the session. |
+| `auto` | SCS only activates for complex tasks, write actions, multi-step shell work, GitHub, system maintenance, Android/iOS, LaTeX/PDF, and long-running tasks. |
+
+`/enabless` should toggle `on` in interactive CLI for the joke and speed. `/enabless auto` can be the mature default later.
+
+## Model Policy
+
+When SCS is enabled:
+
+- Use `mainProvider/mainModel` for committee, student, and supervisor.
+- Set `config.provider/model` to the main role for the run.
+- Keep the spare model disabled unless the user explicitly asks for external critique.
+- Keep parallel scouts disabled by default inside SCS to avoid duplicated advisory layers.
+
+Reasoning:
+
+- The committee and student need enough ability to evaluate plans and evidence.
+- Route model savings are less important because SCS is opt-in for quality.
+- One model family avoids conflicts from tool-call quirks across providers.
+
+Possible future improvement:
+
+- `SCS auto` may use cheap route model for committee drafts, main model for student approval, and main model for supervisor execution. That should be added only after the one-main-model version is reliable.
+
+## UI And CLI
+
+CLI:
+
+```text
+/enabless
+/enabless off
+/enabless auto
+/enabless status
+```
+
+Status output:
+
+```text
+scs=on model=deepseek/deepseek-v4-pro phase=2 decision=phase_accepted
+```
+
+During a run, keep output compact:
+
+```text
+scs committee drafted phase plan
+scs student approved plan confidence=0.82
+scs student requested rethink: repeated blocked write_file
+```
+
+Web:
+
+- Add SCS toggle under Advanced settings first.
+- Show a compact SCS timeline near runtime logs.
+- Do not show raw committee/student transcripts by default; expose them in events/artifacts for inspection.
+
+## Safety And Performance
+
+Bounds:
+
+- Committee plan retries: max 2.
+- Student monitor calls: after plan, before finish, and on triggers; not after every successful tool by default.
+- Evidence pack: last 20 events plus current plan, changed files, tool failures, and acceptance criteria.
+- Transcript budget: summarize old SCS decisions; never append all committee text forever.
+- Failure fallback: if SCS monitor errors, either fail closed for write/system tasks or fail open for read-only tasks with a warning event.
+
+Security:
+
+- Redact tool args with existing redaction helpers.
+- Do not expose secrets in evidence packs.
+- Do not let committee/student call tools.
+- Do not let student approve command-policy violations. Existing guardrails remain authoritative.
+
+## How This Improves AgInTiFlow Beyond The Original Idea
+
+The original idea defines role rights. The more mature design defines event rights.
+
+Better principle:
+
+> No internal role should have abstract authority. It should have permission to emit a small set of typed decisions, and the runtime decides what those decisions can do.
+
+This keeps the system inspectable, testable, and easier to debug.
+
+Recommended mature shape:
+
+- `committee`: proposes structured phase plans.
+- `student`: emits typed gates based on evidence.
+- `supervisor`: executes existing tools under an approved phase.
+- `runtime`: remains the real authority for guardrails, filesystem safety, command policy, session persistence, and user interruption.
+
+This is stronger than a pure multi-agent conversation because it turns role behavior into product behavior.
+
+## Implementation Plan
+
+Implemented first slice:
+
+- `src/scs-controller.js` provides mode normalization, auto activation, committee/student JSON calls, evidence packs, supervisor instructions, tool-failure monitoring, periodic progress review, and final finish gates.
+- `src/config.js` adds `enableScs`/`scsActive` and switches active execution to the main model role when SCS is active.
+- `src/interactive-cli.js` adds `/enabless`, `/enabless auto`, `/enabless off`, `/enabless status`, and `/scs` alias.
+- `src/cli.js` adds `--enabless`, `--enabless auto`, `--no-enabless`, and aliases.
+- `src/agent-runner.js` persists typed `scs.*` events, saves `scs-phase-001.json`, injects the approved supervisor phase, reviews failed tools, and gates finish.
+
+Remaining roadmap:
+
+Phase 1: documentation and config
+
+- Status: implemented for CLI and config.
+
+Phase 2: plan gate
+
+- Status: implemented for the initial phase gate.
+
+Phase 3: execution monitor
+
+- Status: implemented for failed/blocked tools, every-four-steps progress review, and finish gate.
+
+Phase 4: web and tests
+
+- Add web toggle and SCS timeline.
+- Add mock-mode smoke tests for approve, veto, rethink, and finish gate.
+- Add a regression case where the executor tries to finish after a failed tool and student rejects it.
+
+Phase 5: auto mode
+
+- Enable SCS automatically for complex risky profiles after behavior is stable.
+- Keep simple tasks on the current fast pipeline.
+
+## Open Questions
+
+- Should SCS approval be required before any write tool, or only before the first phase starts?
+- Should the student be allowed to require specific checks, or only accept/reject evidence?
+- Should committee be one call or multiple candidate calls synthesized into one plan?
+- Should `/enabless` be hidden as a playful alias while `/scs` is the serious public command?
+- Should SCS decisions be shared through Skill Mesh as learned supervision skills?
+
+## Recommendation
+
+Implement `/enabless` as a serious opt-in quality mode with a playful name.
+
+Start with one-main-model SCS and only gate the initial plan plus final finish. Then add failure-triggered student monitoring. Avoid per-tool approval in the first version; existing command and file guardrails already protect the dangerous paths, and too many monitor calls will make the product feel slow.
+
+The most valuable first success criterion is this:
+
+> In a complex coding task, AgInTiFlow should not execute a weak initial plan, should not keep repeating a failed action, and should not claim completion until a separate monitor has seen evidence.

package/scripts/smoke-aaps-adapter.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { aapsStatus, discoverAaps, formatAapsResult, runAapsAction } from "../src/aaps-adapter.js";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-aaps-adapter-"));
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+async function exists(file) {
+  try {
+    await fs.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const init = await runAapsAction("init", ["Smoke AAPS Project"], { cwd: tempRoot, packageDir: repoRoot });
+assert(init.ok, "AAPS init failed");
+assert(await exists(path.join(tempRoot, "aaps.project.json")), "AAPS init did not write manifest");
+assert(await exists(path.join(tempRoot, "workflows", "main.aaps")), "AAPS init did not write starter workflow");
+
+const files = await runAapsAction("files", [], { cwd: tempRoot, packageDir: repoRoot });
+assert(files.ok && files.files.includes("workflows/main.aaps"), "AAPS files did not find starter workflow");
+
+const status = await aapsStatus({ cwd: tempRoot, packageDir: repoRoot });
+assert(status.ok && status.manifest?.activeFile === "workflows/main.aaps", "AAPS status did not read manifest");
+assert(formatAapsResult(status).includes("AAPS adapter:"), "AAPS status formatter failed");
+
+const discovery = await discoverAaps({ cwd: tempRoot, packageDir: repoRoot });
+if (discovery.found) {
+  const validate = await runAapsAction("validate", [], { cwd: tempRoot, packageDir: repoRoot });
+  assert(validate.ok && validate.json?.ok === true, `AAPS validate failed\n${formatAapsResult(validate)}`);
+
+  const parse = await runAapsAction("parse", [], { cwd: tempRoot, packageDir: repoRoot });
+  assert(parse.ok && parse.json?.pipeline?.name?.includes("Smoke AAPS Project"), `AAPS parse failed\n${formatAapsResult(parse)}`);
+
+  const compile = await runAapsAction("compile", ["check"], { cwd: tempRoot, packageDir: repoRoot });
+  assert(compile.json?.phase?.parse === "ok", `AAPS compile check did not return a structured parse-ok report\n${formatAapsResult(compile)}`);
+  assert(
+    compile.json?.status === "missing_components" || compile.json?.ok === true,
+    `AAPS compile check returned an unexpected status\n${formatAapsResult(compile)}`
+  );
+} else {
+  const validate = await runAapsAction("validate", [], { cwd: tempRoot, packageDir: repoRoot });
+  assert(validate.ok === false && validate.error, "AAPS missing path should return a structured error");
+}
+
+console.log(
+  JSON.stringify(
+    {
+      ok: true,
+      tempRoot,
+      realAaps: discovery.found,
+      source: discovery.source || "",
+      checks: ["init", "files", "status", discovery.found ? "validate/parse/compile" : "missing-error"],
+    },
+    null,
+    2
+  )
+);

package/skills/aaps/SKILL.md

@@ -7,6 +7,8 @@ triggers:
   - .aaps
   - @lazyingart/aaps
   - automation plan
+  - pipeline script
+  - large workflow
 tools:
   - inspect_project
   - read_file
@@ -16,6 +18,25 @@ tools:
 ---
 # AAPS Workflows
 
-Inspect nearby `.aaps` files, package docs, and project notes before generating workflows. Keep assumptions explicit and outputs project-local.
+Use AAPS when the user wants a large workflow, autonomous pipeline script, `.aaps` file, or `@lazyingart/aaps` project.
 
-Do not publish, upload, or expose credentials unless explicitly requested and safe.
+## Operating Loop
+
+1. Inspect `aaps.project.json`, `workflows/*.aaps`, and nearby project notes before generating workflows.
+2. Prefer the AgInTiFlow adapter commands before raw shell guesses:
+   - `/aaps status` or `aginti aaps status`
+   - `/aaps init` or `aginti aaps init`
+   - `/aaps files`
+   - `/aaps validate [file]`
+   - `/aaps parse [file]`
+   - `/aaps compile [file] check`
+   - `/aaps check [file]` or `/aaps dry-run [file]`
+3. Keep all paths project-relative. Do not reference absolute local paths inside reusable `.aaps` files.
+4. Use AAPS for top-down workflow contracts, agent/tool manifests, validation/recovery/review steps, and durable artifacts. Use normal AgInTiFlow file/shell tools for local implementation work under those contracts.
+5. Validate or compile-check every new or edited `.aaps` workflow before reporting it is ready.
+
+## Safety
+
+Do not publish, upload, run destructive commands, or expose credentials unless explicitly requested and safe.
+
+If AAPS is missing, suggest `/aaps install`, `aginti aaps install`, `npm install -g @lazyingart/aaps`, or setting `AAPS_BIN`.