acpus 0.5.2 → 0.6.0-alpha.0

package/skills/acpus/examples/workflows/multi-aspect-brainstorm/workflow.ts

@@ -0,0 +1,304 @@
+import { defineWorkflow, z } from "acpus/core";
+import { eq, ifElse, md } from "acpus/expression";
+
+export default defineWorkflow({
+  name: "multi-aspect-brainstorm",
+  description: "Run multi-aspect brainstorm rounds and synthesize the final result.",
+
+  inputSchema: z.object({
+    rounds: z.number().default(1).describe(
+      "Number of brainstorm rounds to run. Use 1 for a first pass; increase when you want agents to iterate on the latest synthesis.",
+    ),
+    subject: z.string().describe(
+      "The topic, problem, product idea, design question, or decision space to brainstorm.",
+    ),
+    rubric: z.string().describe(
+      "The main goals for the brainstorm, such as desired qualities, success direction, audience, or constraints that should shape the ideas.",
+    ),
+    criteria: z.string().default("").describe(
+      "Optional comma-separated criteria or constraints, for example: cheap, fast to prototype, low operational risk.",
+    ),
+    context: z.string().default("").describe(
+      "Optional background information the agents should consider, such as existing decisions, user needs, project constraints, or prior attempts.",
+    ),
+  }),
+
+  agents: {
+    alpha: {
+      use: "pi",
+    },
+    beta: {
+      use: "pi",
+    },
+    gamma: {
+      use: "claude",
+    },
+    delta: {
+      use: "claude",
+    },
+    synthesizer: {
+      use: "claude",
+    },
+  },
+}).build(({ input, agents, meta, step }) => {
+  const rounds = step("brainstorm_rounds").loop({
+    initial: {
+      round: 0,
+      alpha: "",
+      beta: "",
+      gamma: "",
+      delta: "",
+      synthesis: "",
+    },
+    maxIterations: input.rounds,
+    do: ({ iter, previous, step }) => {
+      const firstRound = eq(iter, 0);
+      const aspects = step("aspect_work").parallel({
+        maxConcurrency: 4,
+        branches: {
+          alpha: {
+            do: ({ step }) => {
+              const aspect = step("alpha_aspect").agent({
+                run: {
+                  agent: agents.alpha,
+                  cwd: meta.workspaceDir,
+                  sessionKey: "alpha-brainstorm",
+                  prompt: md`
+                    ${ifElse(firstRound, md`
+                      You are Alpha in a multi-aspect brainstorm. Your lens is practical solution design and execution paths.
+
+                      Generate feasible directions, implementation shapes, sequencing ideas, and refinements.
+                      Do not approve, reject, score, audit, or produce review findings.
+                      Work independently, but use later round updates to deepen and sharpen your ideas.
+
+                      Subject:
+                      ${input.subject}
+
+                      Context:
+                      ${input.context}
+
+                      Brainstorm goals:
+                      ${input.rubric}
+
+                      Comma-separated useful constraints and selection criteria:
+                      ${input.criteria}
+                    `, "")}
+
+                    Round: ${iter}
+
+                    ${ifElse(firstRound, "Produce your first independent pass.", md`
+                      Continue from the existing Alpha session. Do not restate the setup.
+                      Use the latest synthesis to add practical options, tighten execution paths, and refine tradeoffs.
+
+                      Previous synthesis:
+                      ${previous.synthesis}
+                    `)}
+
+                    Return concise natural-language notes with options, refinements, tradeoffs, and next experiments.
+                  `,
+                },
+                timeout: "45m",
+              });
+
+              return { aspect: aspect.output };
+            },
+          },
+          beta: {
+            do: ({ step }) => {
+              const aspect = step("beta_aspect").agent({
+                run: {
+                  agent: agents.beta,
+                  cwd: meta.workspaceDir,
+                  sessionKey: "beta-brainstorm",
+                  prompt: md`
+                    ${ifElse(firstRound, md`
+                      You are Beta in a multi-aspect brainstorm. Your lens is option expansion, unusual alternatives, and edge-aware constraints.
+
+                      Generate non-obvious directions, neglected constraints, surprising combinations, and ways to keep risk visible while expanding choices.
+                      Do not approve, reject, score, audit, or produce review findings.
+                      Work independently, but use later round updates to broaden and sharpen the option space.
+
+                      Subject:
+                      ${input.subject}
+
+                      Context:
+                      ${input.context}
+
+                      Brainstorm goals:
+                      ${input.rubric}
+
+                      Comma-separated useful constraints and selection criteria:
+                      ${input.criteria}
+                    `, "")}
+
+                    Round: ${iter}
+
+                    ${ifElse(firstRound, "Produce your first independent pass.", md`
+                      Continue from the existing Beta session. Do not restate the setup.
+                      Use the latest synthesis to add alternatives, expose overlooked constraints, and refine tradeoffs.
+
+                      Previous synthesis:
+                      ${previous.synthesis}
+                    `)}
+
+                    Return concise natural-language notes with options, refinements, tradeoffs, and next experiments.
+                  `,
+                },
+                timeout: "45m",
+              });
+
+              return { aspect: aspect.output };
+            },
+          },
+          gamma: {
+            do: ({ step }) => {
+              const aspect = step("gamma_aspect").agent({
+                run: {
+                  agent: agents.gamma,
+                  cwd: meta.workspaceDir,
+                  sessionKey: "gamma-brainstorm",
+                  prompt: md`
+                    ${ifElse(firstRound, md`
+                      You are Gamma in a multi-aspect brainstorm. Your lens is theme clustering, prioritization, and promising combinations.
+
+                      Organize ideas into coherent themes, identify high-leverage priorities, and combine compatible directions into stronger concepts.
+                      Do not approve, reject, score, audit, or produce review findings.
+                      Work independently, but use later round updates to improve structure and synthesis opportunities.
+
+                      Subject:
+                      ${input.subject}
+
+                      Context:
+                      ${input.context}
+
+                      Brainstorm goals:
+                      ${input.rubric}
+
+                      Comma-separated useful constraints and selection criteria:
+                      ${input.criteria}
+                    `, "")}
+
+                    Round: ${iter}
+
+                    ${ifElse(firstRound, "Produce your first independent pass.", md`
+                      Continue from the existing Gamma session. Do not restate the setup.
+                      Use the latest synthesis to cluster ideas, refine priorities, and combine promising directions.
+
+                      Previous synthesis:
+                      ${previous.synthesis}
+                    `)}
+
+                    Return concise natural-language notes with options, refinements, tradeoffs, and next experiments.
+                  `,
+                },
+                timeout: "45m",
+              });
+
+              return { aspect: aspect.output };
+            },
+          },
+          delta: {
+            do: ({ step }) => {
+              const aspect = step("delta_aspect").agent({
+                run: {
+                  agent: agents.delta,
+                  cwd: meta.workspaceDir,
+                  sessionKey: "delta-brainstorm",
+                  prompt: md`
+                    ${ifElse(firstRound, md`
+                      You are Delta in a multi-aspect brainstorm. Your lens is assumptions, missing information, experiments, and alternate framings.
+
+                      Surface assumptions, open questions, small experiments, useful evidence to gather, and reframes that could unlock better ideas.
+                      Do not approve, reject, score, audit, or produce review findings.
+                      Work independently, but use later round updates to enrich the question set and exploration paths.
+
+                      Subject:
+                      ${input.subject}
+
+                      Context:
+                      ${input.context}
+
+                      Brainstorm goals:
+                      ${input.rubric}
+
+                      Comma-separated useful constraints and selection criteria:
+                      ${input.criteria}
+                    `, "")}
+
+                    Round: ${iter}
+
+                    ${ifElse(firstRound, "Produce your first independent pass.", md`
+                      Continue from the existing Delta session. Do not restate the setup.
+                      Use the latest synthesis to add assumptions, questions, experiments, and alternate framings.
+
+                      Previous synthesis:
+                      ${previous.synthesis}
+                    `)}
+
+                    Return concise natural-language notes with options, refinements, tradeoffs, and next experiments.
+                  `,
+                },
+                timeout: "45m",
+              });
+
+              return { aspect: aspect.output };
+            },
+          },
+        },
+      });
+
+      const synthesis = step("synthesize_round").agent({
+        run: {
+          agent: agents.synthesizer,
+          cwd: meta.workspaceDir,
+          sessionKey: "multi-aspect-synthesizer",
+          prompt: md`
+            ${ifElse(firstRound, md`
+              You are the synthesizer for a multi-aspect brainstorm.
+              Combine independent aspect outputs into a useful idea map.
+              Do not approve, reject, score, audit, or produce review findings.
+
+              Subject:
+              ${input.subject}
+
+              Context:
+              ${input.context}
+
+              Brainstorm goals:
+              ${input.rubric}
+
+              Comma-separated useful constraints and selection criteria:
+              ${input.criteria}
+            `, "")}
+
+            Round: ${iter}
+
+            ${ifElse(firstRound, "Produce the clearest idea map for this first round.", "Continue from the existing synthesizer session. Produce the clearest idea map for this round.")}
+            Do not average opinions mechanically.
+
+            Current aspect outputs:
+            Alpha: ${aspects.output.alpha.aspect}
+            Beta: ${aspects.output.beta.aspect}
+            Gamma: ${aspects.output.gamma.aspect}
+            Delta: ${aspects.output.delta.aspect}
+
+            Return a concise natural-language synthesis with strongest directions, notable alternatives, tradeoffs, open questions, and next exploration steps.
+          `,
+        },
+        timeout: "45m",
+      });
+
+      return {
+        round: iter,
+        alpha: aspects.output.alpha.aspect,
+        beta: aspects.output.beta.aspect,
+        gamma: aspects.output.gamma.aspect,
+        delta: aspects.output.delta.aspect,
+        synthesis: synthesis.output,
+      };
+    },
+    onExhausted: "returnLast",
+  });
+
+  return { synthesis: rounds.output.synthesis };
+});

package/skills/acpus/examples/workflows/worktree-tournament/workflow.ts

@@ -0,0 +1,194 @@
+import { defineWorkflow, z } from "acpus/core";
+import { md, template } from "acpus/expression";
+import { createWorktree } from "acpus/tasks/git";
+
+export default defineWorkflow({
+  name: "worktree-tournament",
+  description: "Create competing worktree implementations and have an agent judge the best result.",
+  inputSchema: z.object({
+    repoPath: z.path().describe("Source repository path used to create candidate worktrees and run the judge."),
+    worktreeRoot: z.path().describe("Directory where per-run candidate worktrees should be created."),
+    task: z.string().describe("Implementation task each candidate agent should attempt independently."),
+    baseRef: z.string().default("HEAD").describe("Git ref used as the base for each candidate worktree."),
+    forceRemove: z.boolean().default(false).describe(
+      "Whether createWorktree may remove an existing candidate worktree path before recreating it.",
+    ),
+  }),
+  agents: {
+    implementer: { use: "codex" },
+    judge: { use: "codex" },
+  },
+}).build(({ input, agents, meta, step }) => {
+  const paths = step("plan_worktrees").task({
+    run: {
+      input: { root: input.worktreeRoot, runId: meta.runId },
+      exec: async ({ input }) => ({
+        alpha: `${input.root}/${input.runId}-alpha`,
+        beta: `${input.root}/${input.runId}-beta`,
+        gamma: `${input.root}/${input.runId}-gamma`,
+      }),
+    },
+  });
+
+  const candidates = step("candidate_worktrees").parallel({
+    branches: {
+      alpha: {
+        do: ({ step }) => {
+          const worktree = step("create_alpha_worktree").task({
+            run: {
+              task: createWorktree,
+              input: {
+                repo: input.repoPath,
+                path: paths.output.alpha,
+                ref: input.baseRef,
+                forceRemove: input.forceRemove,
+              },
+            },
+            timeout: "2m",
+          });
+
+          const implementation = step("implement_alpha").agent({
+            run: {
+              agent: agents.implementer,
+              cwd: worktree.output.worktreePath,
+              prompt: md`
+                Implement this task in the alpha worktree.
+
+                Task: ${input.task}
+
+                Return a Markdown implementation report with:
+                - Changed files
+                - Implementation summary
+                - Test command run, or "not run" with the reason
+              `,
+            },
+            timeout: "45m",
+          });
+
+          return {
+            lane: "alpha",
+            worktreePath: worktree.output.worktreePath,
+            report: implementation.output,
+          };
+        },
+      },
+      beta: {
+        do: ({ step }) => {
+          const worktree = step("create_beta_worktree").task({
+            run: {
+              task: createWorktree,
+              input: {
+                repo: input.repoPath,
+                path: paths.output.beta,
+                ref: input.baseRef,
+                forceRemove: input.forceRemove,
+              },
+            },
+            timeout: "2m",
+          });
+
+          const implementation = step("implement_beta").agent({
+            run: {
+              agent: agents.implementer,
+              cwd: worktree.output.worktreePath,
+              prompt: md`
+                Implement this task in the beta worktree.
+
+                Task: ${input.task}
+
+                Return a Markdown implementation report with:
+                - Changed files
+                - Implementation summary
+                - Test command run, or "not run" with the reason
+              `,
+            },
+            timeout: "45m",
+          });
+
+          return {
+            lane: "beta",
+            worktreePath: worktree.output.worktreePath,
+            report: implementation.output,
+          };
+        },
+      },
+      gamma: {
+        do: ({ step }) => {
+          const worktree = step("create_gamma_worktree").task({
+            run: {
+              task: createWorktree,
+              input: {
+                repo: input.repoPath,
+                path: paths.output.gamma,
+                ref: input.baseRef,
+                forceRemove: input.forceRemove,
+              },
+            },
+            timeout: "2m",
+          });
+
+          const implementation = step("implement_gamma").agent({
+            run: {
+              agent: agents.implementer,
+              cwd: worktree.output.worktreePath,
+              prompt: md`
+                Implement this task in the gamma worktree.
+
+                Task: ${input.task}
+
+                Return a Markdown implementation report with:
+                - Changed files
+                - Implementation summary
+                - Test command run, or "not run" with the reason
+              `,
+            },
+            timeout: "45m",
+          });
+
+          return {
+            lane: "gamma",
+            worktreePath: worktree.output.worktreePath,
+            report: implementation.output,
+          };
+        },
+      },
+    },
+  });
+
+  const judgment = step("judge_candidates").agent({
+    outputSchema: z.object({
+      winner: z.enum(["alpha", "beta", "gamma"]),
+      rationale: z.string(),
+    }),
+    run: {
+      agent: agents.judge,
+      cwd: input.repoPath,
+      prompt: md`
+        Judge the best implementation for this task.
+
+        Task: ${input.task}
+
+        Each candidate includes its lane, worktree path, and Markdown implementation report.
+
+        Alpha: ${candidates.output.alpha}
+        Beta: ${candidates.output.beta}
+        Gamma: ${candidates.output.gamma}
+
+        Return the winning lane and a concise rationale.
+      `,
+    },
+    retry: { max: 1 },
+    timeout: "30m",
+  });
+
+  return {
+    runId: meta.runId,
+    winner: judgment.output.winner,
+    rationale: judgment.output.rationale,
+    candidates: {
+      alpha: candidates.output.alpha,
+      beta: candidates.output.beta,
+      gamma: candidates.output.gamma,
+    },
+  };
+});

package/skills/acpus/references/authoring.md

@@ -0,0 +1,205 @@
+# Authoring Workflows
+
+## Quick Start
+
+### Imports
+
+Use TypeScript workflow modules and user-facing facades only:
+
+```ts
+import { defineWorkflow, task, secret, z } from "acpus/core";
+import { template, md, and, eq, lte, coalesce, len, head, get, filter, map, where, not, or, gte, includes, ifElse, ne, lt, gt, isEmpty, startsWith, endsWith, matches, every, some, max, min, pick } from "acpus/expression";
+import { createWorktree } from "acpus/tasks/git";
+```
+
+Do not import `@acpus/*` from user workflows; those are implementation packages behind the `acpus/*` facades.
+
+### Minimal Workflow Skeleton
+
+```ts
+import { defineWorkflow, z } from "acpus/core";
+import { template } from "acpus/expression";
+
+export default defineWorkflow({
+  name: "my-workflow",
+  description: "Analyze a topic in a repository.",
+  inputSchema: z.object({ repoPath: z.path(), topic: z.string() }),
+  agents: { worker: { use: "codex" } },
+}).build(({ input, agents, meta, step }) => {
+  const result = step("work").agent({
+    outputSchema: z.object({ ok: z.boolean(), summary: z.string() }),
+    run: { agent: agents.worker, prompt: template`Analyze ${input.topic} in ${input.repoPath}.` },
+  });
+  return { runId: meta.runId, ok: result.output.ok, summary: result.output.summary };
+});
+```
+
+## Mental Model
+
+### Why Expressions Exist
+
+Acpus workflows are a TypeScript-authored DSL, not ordinary runtime TypeScript. `build` declares a durable graph before a run executes, so workflow input, metadata, and prior node outputs are graph values wrapped as `Expr<T>` tokens. Treat every run-dependent value as an expression token and use graph constructs plus `acpus/expression` helpers to combine, compare, select, and render those values. Use plain JavaScript only for authoring-time constants and task `exec` bodies.
+
+### Expressions And Templates
+
+Expression helpers:
+
+| Do not write | Write |
+| --- | --- |
+| `input.ready && output.ok` | `and(input.ready, output.ok)` |
+| `input.kind === "release"` | `eq(input.kind, "release")` |
+| `risk <= 3` | `lte(risk, 3)` |
+| `input.maybe ?? "fallback"` | `coalesce(input.maybe, "fallback")` |
+| `` `topic ${input.topic}` `` | `template\`topic ${input.topic}\`` |
+| `input.items.length` | `len(input.items)` |
+| `items[0]` | `head(items)` or `get(items, 0)` |
+
+For collections: `filter(input.items, item => where(item, { tags: { contains: "ready" } }))`, `map(ready, item => item.id)`, `len(ready)`, `coalesce(head(readyIds), "(none)")`.
+
+Use `template` for compact strings and `md` for multiline prompts/messages; `md` trims surrounding blank lines and common indentation while preserving expression interpolation.
+
+### Boundary Schemas
+
+Boundary schemas use `z` from `acpus/core`. Use `z.path()` for filesystem paths crossing workflow boundaries.
+
+Keep workflow input, Agent output, Signal output, and reusable task input JSON-compatible and durable. Avoid transforms, functions, promises, maps, sets, dates, bigint, symbol, `undefined`, `void`, `never`, non-finite numbers, sparse arrays, cycles, and class instances in graph-boundary values or runtime outputs.
+
+## Workflow Building Blocks
+
+### Tasks
+
+Task nodes run deterministic local glue, write artifacts, and infer output from `exec`:
+
+```ts
+const prepared = step("prepare").task({
+  run: {
+    input: { repoPath: input.repoPath },
+    cwd: input.repoPath,
+    exec: async ({ input, $, artifact, abortSignal }) => {
+      const status = await $`git status --short`;
+      return { dirty: status.stdout.trim().length > 0, statusFile: await artifact.writeText("status.txt", status.stdout, { mediaType: "text/plain" }) };
+    },
+  },
+  timeout: "2m",
+});
+```
+
+Reusable tasks own their input schema and executable body:
+
+```ts
+// tasks/normalize-name.ts
+import { task, z } from "acpus/core";
+import slugify from "slugify";
+
+export const normalizeName = task.define({
+  inputSchema: z.object({ name: z.string() }),
+  exec: async ({ input }) => ({ slug: slugify(input.name, { lower: true }) }),
+});
+```
+
+```ts
+import { normalizeName } from "./tasks/normalize-name.js";
+const normalized = step("normalize").task({ run: { task: normalizeName, input: { name: input.name } } });
+```
+
+Inline task source is embedded in frozen IR. Pass workflow values through `run.input` and use only task context (`input`, `$`, `artifact`, `env`, `abortSignal`) inside `exec`.
+
+### Agents
+
+Agent nodes handle judgment, synthesis, planning, and review:
+
+```ts
+const review = step("review").agent({
+  outputSchema: z.object({ ready: z.boolean(), summary: z.string() }),
+  run: { agent: agents.reviewer, prompt: template`Review artifact ${prepared.output.statusFile}.`, cwd: input.repoPath },
+  retry: { max: 2 },
+  timeout: "30m",
+});
+```
+
+Top-level agent definitions use either `use` or `command`, never both. Agent nodes without `outputSchema` return `Expr<string>`. The default `permissionMode` is write-capable.
+
+### Agent Selection
+
+Native acpx `use` names include `pi`, `codex`, `claude`, `gemini`, `cursor`, `copilot`, `droid`, `fast-agent`, `grok-build`, `iflow`, `kilocode`, `kimi`, `kiro`, `mux`, `opencode`, `qoder`, `qwen`, and `trae`; for the current list, see https://github.com/openclaw/acpx/tree/main/agents.
+
+For agents not natively supported by acpx, use `command: "<acp command>"`, for example `{ command: "npx pi-acp" }`.
+
+### Signals And Asserts
+
+Signal nodes wait for operator input:
+
+```ts
+const approval = step("approval").signal({
+  outputSchema: z.object({ approved: z.boolean(), notes: z.string().default("") }),
+  run: { prompt: template`Approve the result: ${review.output.summary}` },
+  timeout: "24h",
+  onTimeout: { action: "fail", message: "Approval timed out" },
+});
+```
+
+Assert nodes fail the run when an expression condition is false:
+
+```ts
+step("require_approval").assert({ condition: approval.output.approved, message: template`Approval denied: ${approval.output.notes}` });
+```
+
+### Composites
+
+Graph-level composites:
+
+- `if`: conditional branch; both branches should return compatible object shapes.
+- `switch`: case list plus required `default` branch.
+- `parallel`: static named branches; `strategy` defaults to `"all"`, with `"race"` available.
+- `fanout`: runtime array expansion; output is an array. `strategy` defaults to `"all"`, with `"quorum"` available.
+- `loop`: seeded pre-check loop. `maxIterations` counts body executions only; `stopWhen` checks before each body execution.
+
+Composite callbacks receive `{ step }` plus composite-specific values such as `item`, `iter`, and `previous`. Return a plain object to declare composite output; do not add `outputSchema` to composites. For `parallel({ strategy: "race" })`, output is `{ winner, result }`, not a branch-keyed object. For `fanout({ strategy: "quorum", count })`, output is the accepted item array, not an envelope.
+
+## Best Practices
+
+### Structured Boundaries
+
+- Use the smallest structured boundary that the workflow actually needs.
+- Omit `outputSchema` when natural-language text is enough.
+- Add schemas only for values the workflow must branch on, fan out over, assert, or expose as machine-readable final output.
+- Let agents exchange Markdown when later agents can read the result directly.
+
+### Agent Sessions And Permissions
+
+- When the user has no agent preference, ask which agent to use.
+- Check local availability with `command -v <binary>` before recommending a local agent.
+- Use `acpus runs retry` for control-plane retry after a failed run.
+- Omit `sessionKey` by default; set it only when a multi-turn loop explicitly needs the agent to reuse one session.
+- Omit `permissionMode` for normal authoring; use `permissionMode: "approve-reads"` only for agents that are explicitly not allowed to write, such as audit-only inspection.
+
+### Task Boundaries
+
+- Put reusable tasks in separate task modules when they need shared code or third-party packages installed with the workflow package.
+- Keep inline tasks self-contained: no third-party imports, module-scope environment reads, or module-scope captures.
+
+### Expression And Schema Hygiene
+
+- Start from the examples; inspect declarations only when the examples do not answer the API question.
+- Use graph-level composites instead of JavaScript control flow over expression values.
+- Use expression helpers instead of native operators/properties over expression values.
+- Use `template` for compact strings and `md` for multiline prompts/messages.
+- Use signal nodes only when the workflow needs external control.
+- Keep graph-boundary schema values JSON-compatible and durable.
+
+## Validation And API Lookup
+
+### Workflow Check
+
+`acpus workflow check <workflow.ts-or-catalog>` prepares the workflow in memory and catches TypeScript diagnostics plus Acpus authoring diagnostics such as Expr truthiness, native operators over Expr values, dynamic node ids, task callsites that cannot be joined to task metadata, inline task captures, and non-admissible outputs.
+
+Run `acpus workflow check <workflow.ts-or-catalog>` before admitting a run.
+
+### Declaration Lookup
+
+When exact API usage is unclear, inspect installed declarations instead of copied reference prose:
+
+1. Start from the global install: `$(npm root -g)/acpus/dist/authoring/`.
+2. Read facade declarations there: `core.d.ts`, `expression.d.ts`, and `tasks/git.d.ts`.
+3. Follow re-exports into sibling global packages: `$(npm root -g)/@acpus/core/dist/*.d.ts`, `@acpus/expression/dist/*.d.ts`, and `@acpus/tasks/dist/*.d.ts`.
+4. Retrieve only the relevant symbol plus nearby doc comment/signature; do not dump full declaration files.