@zibby/skills 0.2.22 → 0.2.24

package/docs/concepts/sub-graphs.md

@@ -1,227 +0,0 @@
----
-sidebar_position: 6
-title: Sub-graphs (parent → child)
----
-
-# Sub-graphs
-
-A **sub-graph node** runs another deployed agent as a child of the current one. Use it when a step is large enough to deserve its own workflow definition — its own state schema, its own version, its own activity-tab history — but you want a parent to dispatch it as part of a larger flow.
-
-The shape is one extra field on the existing node config:
-
-```js
-g.addNode('audit', {
-  workflow: 'deep-audit',   // ← name of another agent in this project
-});
-```
-
-That's it. No new imports, no UUID, no separate class. The engine recognizes `workflow:` and turns this node into a sub-graph dispatcher.
-
-## When to use a sub-graph
-
-| Scenario | Sub-graph? |
-|---|---|
-| Two parents need the same multi-node flow | ✅ Yes — define it once as a child, reference by name |
-| One step needs different state schema than the rest | ✅ Yes — each agent has its own schema |
-| You want per-step activity-tab history + replay | ✅ Yes — each child run gets its own row |
-| Step is a single LLM call | ❌ No — just add a regular node |
-| Step has its own retry policy | Either works, but a sub-graph gives independent control |
-
-## Sync vs async
-
-`async:` flips the dispatch mode:
-
-```js
-g.addNode('audit',  { workflow: 'deep-audit' });                  // sync (default)
-g.addNode('notify', { workflow: 'slack-notifier', async: true }); // fire-and-forget
-```
-
-| Mode | Behavior | Returns to parent | Use for |
-|---|---|---|---|
-| **sync** (default) | Parent blocks, polls child until terminal status, merges result into parent state | the extracted value (see `output:` below) | Steps where downstream nodes depend on the child's result |
-| **async** (`async: true`) | Parent dispatches the child and continues immediately. No polling. | a dispatch handle `{ jobId, status, workflow }` | Fan-out, notifications, side-effect work the parent shouldn't wait for |
-
-Quota: every sub-graph run counts as a separate execution against the account's monthly cap (parent + 3 children = 4 executions).
-
-## Full option surface
-
-```js
-g.addNode('audit', {
-  // ─── Required ─────────────────────────────────────────────────────
-  workflow: 'deep-audit',          // resolved by name within this project
-
-  // ─── Mode (default sync) ──────────────────────────────────────────
-  async: false,                    // false = block + merge, true = fire-forget
-
-  // ─── State plumbing ───────────────────────────────────────────────
-  input: (state) => ({             // shape parent state → child input
-    ticketId: state.ticketId,
-  }),                              // OR a plain object  OR omit (child gets {})
-
-  output: 'audit.score',           // dot-path on child finalState
-                                   // OR (childState) => ({...})  function form
-                                   // OR omit → entire child finalState
-
-  // ─── Sync tunings (ignored when async: true) ──────────────────────
-  timeoutMs: 5 * 60 * 1000,        // throw after this long (default 10min)
-  pollIntervalMs: 2000,            // status-check frequency (default 2s)
-
-  // ─── Cross-cutting concerns ───────────────────────────────────────
-  retries: 3,                      // engine retries whole dispatch on transient failure
-  onComplete: (state, result) => result,
-
-  // ─── Advanced ─────────────────────────────────────────────────────
-  conversationId: 'inherit',       // 'inherit' (default) | 'new' | (state) => string
-});
-```
-
-## How state flows
-
-Each agent has its own state schema — they're independent. The parent must transform its state into the child's input shape, and (optionally) extract whatever it needs back out.
-
-### A complete example — `parent-orchestrator` calls `child-doubler`
-
-```js
-// child-doubler — takes a number, returns it doubled.
-class ChildDoublerAgent extends WorkflowAgent {
-  buildGraph() {
-    const g = new WorkflowGraph();
-    g.setStateSchema(z.object({
-      value:  z.number(),
-      double: z.object({ doubled: z.number() }).optional(),
-    }));
-    g.addNode('double', {
-      _isCustomCode: true,
-      outputSchema: z.object({ doubled: z.number() }),
-      execute: async (ctx) => ({ doubled: ctx.state.getAll().value * 2 }),
-    });
-    g.setEntryPoint('double');
-    g.addEdge('double', 'END');
-    return g;
-  }
-}
-
-// parent-orchestrator — picks a number, calls child-doubler, reports.
-class ParentOrchestratorAgent extends WorkflowAgent {
-  buildGraph() {
-    const g = new WorkflowGraph();
-    g.setStateSchema(z.object({
-      seed:         z.number(),
-      pick_number:  z.object({ value: z.number(), label: z.string() }).optional(),
-      call_doubler: z.number().optional(),       // ← child's result lands here
-      report:       z.object({ summary: z.string() }).optional(),
-    }));
-
-    g.addNode('pick_number', pickNumberNode);
-
-    g.addNode('call_doubler', {
-      workflow: 'child-doubler',
-      input:  (state) => ({ value: state.pick_number.value }),
-      output: 'double.doubled',                  // dot-path through child's node name
-    });
-
-    g.addNode('report', reportNode);             // reads state.call_doubler
-
-    g.setEntryPoint('pick_number');
-    g.addEdge('pick_number', 'call_doubler');
-    g.addEdge('call_doubler', 'report');
-    g.addEdge('report', 'END');
-    return g;
-  }
-}
-```
-
-Triggering the parent with `{ seed: 21 }`:
-
-| Step | What happens | State after |
-|---|---|---|
-| 1 | `pick_number` runs | `{ seed: 21, pick_number: { value: 21, label: '…' } }` |
-| 2 | `call_doubler.input(state)` fires | returns `{ value: 21 }` |
-| 3 | Server validates `{ value: 21 }` against child's `stateSchema` | passes |
-| 4 | Child runs in its own Fargate task. Final state: `{ value: 21, double: { doubled: 42 } }` | (parent waiting) |
-| 5 | Engine extracts `output: 'double.doubled'` → `42` | `state.call_doubler = 42` |
-| 6 | `report` runs, reads `state.call_doubler` | `state.report.summary = '…42…'` |
-
-### Why `output: 'double.doubled'` and not `'doubled'`?
-
-Each node's output is stored at `state[nodeName]` in its own graph. So when the child's `double` node returns `{ doubled: 42 }`, that lands at `childState.double.doubled` — `doubled` is *nested under the node name*, not promoted to the top level.
-
-If you want multiple fields, use the function form:
-
-```js
-output: (childState) => ({
-  doubled:  childState.double.doubled,
-  echoed:   childState.value,
-  isDouble: childState.double.doubled === childState.value * 2,
-}),
-// → state.audit = { doubled: 42, echoed: 21, isDouble: true }
-```
-
-Or omit `output:` and the entire `childState` lands at `state[nodeName]` — useful when you don't know yet which fields you'll need.
-
-## Schema validation at the boundary
-
-The server runs the same input gate sub-graph triggers hit as user-initiated ones. If the parent's `input:` callback returns a value that doesn't satisfy the child's `stateSchema`, the trigger 400s **before** any Fargate spawn — no wasted compute. The parent's sub-graph node throws a typed error with the missing fields listed.
-
-## Errors
-
-Sub-graph failures throw with a `code` field so you can branch:
-
-| `err.code` | Meaning | Useful properties |
-|---|---|---|
-| `SUBGRAPH_INVALID_INPUT` | Parent's `input:` produced data that violates the child's stateSchema | `err.missing[]`, `err.validationErrors` |
-| `SUBGRAPH_QUOTA_EXCEEDED` | Account is over its execution cap; child can't dispatch | `err.quotaInfo` |
-| `SUBGRAPH_TRIGGER_FAILED` | Any other HTTP failure from the trigger endpoint | `err.status` |
-
-Sync-mode terminal failures (child completed in `failed` / `canceled` / `timeout`):
-
-```js
-err.subgraphJobId      // child's executionId — look up in activity tab
-err.subgraphStatus     // 'failed' | 'canceled' | 'timeout'
-```
-
-`retries:` on the sub-graph node re-runs the whole dispatch (trigger + poll) on transient failures, same semantics as a regular node retry.
-
-## What's deployed vs what you write
-
-You only ever reference agents by **name**. The cloud handles the UUID resolution.
-
-| Stage | What you write | What the backend does |
-|---|---|---|
-| `zibby agent deploy child-doubler` | nothing about UUIDs | mints UUID, stores `(projectId, workflowType='child-doubler', uuid='…')` |
-| `subgraph('child-doubler')` in parent code | just the name | stored as a string in the parent's graph definition |
-| `zibby agent deploy parent-orchestrator` | nothing | looks up `'child-doubler'` → UUID, snapshots the dependency |
-| Parent runs in Fargate → hits sub-graph node | nothing | POSTs to `/workflows/<uuid>/trigger` with `parentExecutionId` |
-
-Names are unique per project (DDB primary key enforces this), so `subgraph('child-doubler')` resolves unambiguously within the parent's project.
-
-## Activity-tab tree-view
-
-Each child execution row carries `parentExecutionId` pointing at the parent. The activity tab uses this to render parent runs as collapsible groups — expand to see the chain of children.
-
-| Row | `parentExecutionId` | Type |
-|---|---|---|
-| Parent (orchestrator) | `null` | top-level (user-triggered) |
-| Child (doubler) | `<parent's executionId>` | dispatched as sub-graph |
-
-## Local development
-
-Sub-graph dispatch needs the `PROGRESS_API_URL` env var (the public API base). That's set automatically on Fargate runs. For local dev, you have two options:
-
-1. **Deploy both agents to cloud, then trigger the parent.** The cloud path always works.
-2. **Mock the trigger + status endpoints locally.** See [`workflows/parent-orchestrator/mock-server.mjs`](https://github.com/ZibbyDev/agent-workflow/tree/main/examples) in the agent-workflow repo for a 90-line example that simulates the dispatch + poll loop.
-
-In-process sub-graph execution (running the child in the parent's Node process directly, no HTTP) is **not supported** — we picked consistency between local and cloud over the 10s spawn-time savings.
-
-## Cross-project sub-graphs
-
-`workflow: 'name'` resolves within the parent's own project. To call another project's agent, pass an explicit project ID:
-
-```js
-g.addNode('audit', {
-  workflow: 'shared-audit',
-  project:  'b6219c3a-…',   // explicit cross-project reference
-});
-```
-
-The caller must have access to the destination project (same account, or invited). Cross-**account** sub-graphs are not in v1.

package/docs/custom-workflows.md

@@ -1,358 +0,0 @@
----
-sidebar_position: 5
-title: Custom Workflows
----
-
-# Custom Workflows
-
-Build, test, and deploy your own AI workflows using Zibby's graph-based framework. Custom workflows let you define multi-step AI pipelines that run locally or in Zibby Cloud, triggered via API or subdomain URL.
-
-## Quick Start
-
-```bash
-# 1. Scaffold a new workflow
-zibby g workflow ticket-triage
-
-# 2. Test locally
-zibby start ticket-triage
-
-# 3. Deploy to cloud
-zibby deploy ticket-triage --project <project-id>
-
-# 4. Trigger via API
-curl -X POST https://ticket-triage-6af9.workflows.zibby.app \
-  -H "Authorization: Bearer $ZIBBY_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"input": {"ticket": "BUG-123"}}'
-
-# 5. Tail logs
-zibby logs --workflow ticket-triage --project <project-id>
-```
-
-## Scaffolding
-
-```bash
-zibby g workflow <name>
-```
-
-If you omit the name, Zibby generates a random one (like Heroku app names).
-
-This creates:
-
-```
-.zibby/workflows/<name>/
-├── graph.mjs          # Workflow class (entry point)
-├── nodes/
-│   ├── index.mjs      # Barrel export
-│   └── example.mjs    # Starter node with prompt + schema
-└── workflow.json       # Manifest (metadata, triggers)
-```
-
-### Workflow Structure
-
-**`graph.mjs`** — Defines the workflow class that extends `WorkflowAgent`:
-
-```javascript
-import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
-import { exampleNode } from './nodes/index.mjs';
-
-export class TicketTriageWorkflow extends WorkflowAgent {
-  buildGraph() {
-    const graph = new WorkflowGraph();
-
-    graph.addNode('example', exampleNode);
-    graph.setEntryPoint('example');
-    graph.addEdge('example', 'END');
-
-    return graph;
-  }
-
-  async onComplete(result) {
-    console.log(`Workflow complete — success: ${result.success !== false}`);
-  }
-}
-```
-
-**`nodes/example.mjs`** — Each node has a prompt function and a Zod output schema:
-
-```javascript
-import { z } from '@zibby/core';
-
-const ExampleOutputSchema = z.object({
-  summary: z.string().describe('A short summary of the result'),
-  status: z.enum(['ok', 'warn', 'error']).describe('Overall status'),
-});
-
-export const exampleNode = {
-  name: 'example',
-  prompt: (state) => `You are a helpful workflow node.
-
-Input:
-${JSON.stringify(state.input || {}, null, 2)}
-
-Analyze the input and return a summary with a status.`,
-  outputSchema: ExampleOutputSchema,
-};
-```
-
-**`workflow.json`** — Manifest with metadata:
-
-```json
-{
-  "name": "ticket-triage",
-  "triggers": { "api": true }
-}
-```
-
-## Adding Nodes
-
-Create a new file in `nodes/` and wire it into the graph:
-
-```javascript
-// nodes/classify.mjs
-import { z } from '@zibby/core';
-
-const ClassifySchema = z.object({
-  priority: z.enum(['critical', 'high', 'medium', 'low']),
-  category: z.string(),
-  assignTo: z.string().optional(),
-});
-
-export const classifyNode = {
-  name: 'classify',
-  prompt: (state) => `Given this ticket summary:
-${state.example.summary}
-
-Classify the priority, category, and suggested assignee.`,
-  outputSchema: ClassifySchema,
-};
-```
-
-Then add it to `graph.mjs`:
-
-```javascript
-import { classifyNode } from './nodes/classify.mjs';
-
-// In buildGraph():
-graph.addNode('classify', classifyNode);
-graph.addEdge('example', 'classify');  // instead of example → END
-graph.addEdge('classify', 'END');
-```
-
-### Conditional Edges
-
-Route to different nodes based on output:
-
-```javascript
-graph.addConditionalEdges('classify', (state) => {
-  return state.classify.priority === 'critical' ? 'escalate' : 'notify';
-});
-```
-
-## Local Development
-
-### Start a dev server
-
-```bash
-zibby start ticket-triage
-zibby start ticket-triage --port 3850
-```
-
-This starts a local HTTP server that loads your workflow and exposes a trigger endpoint:
-
-```bash
-curl -X POST http://localhost:3848/trigger \
-  -H "Content-Type: application/json" \
-  -d '{"input": {"ticket": "BUG-456"}}'
-```
-
-The dev server uses your local `.zibby.config.mjs` for agent configuration (model, API keys, etc.) — the same config used by `zibby test`.
-
-## Deploying to Cloud
-
-### Prerequisites
-
-1. **Authenticated**: Run `zibby login` (or set `ZIBBY_API_KEY`)
-2. **Project**: Have a project ID (run `zibby list` to see yours)
-
-### Deploy
-
-```bash
-zibby deploy ticket-triage --project <project-id>
-```
-
-This:
-1. Loads and serializes the workflow graph
-2. Bundles all source files (`.mjs`, `.js`, `.json`)
-3. Uploads to Zibby Cloud
-4. Registers a unique subdomain
-
-Output:
-
-```
-  Workflow "ticket-triage" deployed to version 1
-
-  Trigger URL (API):
-    POST https://api-prod.zibby.app/projects/<id>/workflows/ticket-triage/trigger
-
-  Trigger URL (subdomain):
-    POST https://ticket-triage-6af9.workflows.zibby.app
-
-  Tail logs:
-    zibby logs <jobId> --project <id>
-```
-
-### Subdomain URLs
-
-Each deployed workflow gets a globally unique subdomain:
-
-```
-https://<workflow-name>-<hash>.workflows.zibby.app
-```
-
-The hash is a short (4-char) deterministic suffix derived from your project ID, ensuring uniqueness across all projects.
-
-### Authentication
-
-Both trigger URLs require authentication via the `Authorization` header:
-
-- **JWT token** — from `zibby login` session
-- **Personal Access Token (PAT)** — from your project settings (`zby_xxx`)
-
-```bash
-curl -X POST https://ticket-triage-6af9.workflows.zibby.app \
-  -H "Authorization: Bearer zby_your_api_key" \
-  -H "Content-Type: application/json" \
-  -d '{"input": {"ticket": "BUG-789"}}'
-```
-
-### How Cloud Execution Works
-
-When triggered, the workflow runs in an isolated ECS Fargate container:
-
-1. Lambda receives the trigger request
-2. Workflow sources are loaded from DynamoDB and uploaded to S3
-3. A Fargate task is launched with the workflow code
-4. The container downloads sources, rebuilds the graph, and executes it
-5. Agent configuration (model, API keys) comes from your project settings
-
-Each run is fully isolated — no shared state between runs.
-
-## Cloning Repositories
-
-Custom workflows can clone your project's configured repositories using the `cloneRepo()` helper:
-
-```javascript
-import { cloneRepo } from '@zibby/core';
-
-// In a node's preProcess function
-const repoPaths = await cloneRepo();
-// Returns: { 'myorg/backend': '/workspace/repos/myorg-backend', ... }
-```
-
-This gives your workflow access to your actual codebase for analysis, testing, or deployment tasks.
-
-**[See the full Cloning Repositories guide →](./cloning-repositories.md)**
-
-## Tailing Logs
-
-### Tail a specific job
-
-The trigger API returns a `jobId`. Use it to tail logs:
-
-```bash
-zibby logs <jobId> --project <project-id>
-```
-
-### Tail the latest run
-
-```bash
-zibby logs --workflow ticket-triage --project <project-id>
-```
-
-This lists recent runs and automatically tails the latest one.
-
-### All runs (interleaved)
-
-```bash
-zibby logs --workflow ticket-triage --all --project <project-id>
-```
-
-Shows logs from all past runs of the workflow, sorted chronologically with job ID separators:
-
-```
-  ── wfj-1713157331-a3 ──
-2026-04-15 14:02:11  🚀 Starting ticket-triage workflow...
-2026-04-15 14:02:18  ✅ Workflow complete
-
-  ── wfj-1713157522-b7 ──
-2026-04-15 14:05:22  🚀 Starting ticket-triage workflow...
-2026-04-15 14:05:30  Running node: example
-```
-
-### Options
-
-| Flag | Description |
-|---|---|
-| `--project <id>` | Project ID (or `ZIBBY_PROJECT_ID` env) |
-| `--workflow <name>` | Workflow name (tails latest run) |
-| `--all` | Interleaved logs from all runs (requires `--workflow`) |
-| `--no-follow` | Fetch logs once, don't stream |
-| `--lines <n>` | Max lines per fetch (default: 200) |
-
-## Agent Configuration
-
-### Local
-
-Local execution uses your `.zibby.config.mjs`:
-
-```javascript
-export default {
-  agent: {
-    cursor: { model: 'auto' },
-    // claude: { model: 'sonnet-4.6' },
-  },
-};
-```
-
-API keys come from environment variables (`CURSOR_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`).
-
-### Cloud
-
-Cloud execution uses your **project settings** (configured in the Zibby dashboard):
-
-- **AI Agent** — which agent to use (Cursor, Claude, Codex, Gemini)
-- **Model** — model override
-- **API Key** — stored encrypted, injected into the container at runtime
-
-No config files are needed in the cloud — everything is read from project settings.
-
-## Self-Hosting
-
-You can run workflows on your own infrastructure without Zibby Cloud. Your server just needs:
-
-1. `@zibby/core` and `@zibby/cli` npm packages
-2. Environment variables for agent configuration:
-
-```bash
-AGENT_TYPE=cursor          # or claude, codex, gemini
-MODEL=auto
-CURSOR_API_KEY=sk-xxx      # or ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY
-```
-
-Then trigger the workflow programmatically:
-
-```javascript
-import { WorkflowGraph } from '@zibby/core';
-import { TicketTriageWorkflow } from './.zibby/workflows/ticket-triage/graph.mjs';
-
-const agent = new TicketTriageWorkflow();
-const graph = agent.buildGraph();
-const result = await graph.run(agent, { input: { ticket: 'BUG-123' } });
-```
-
-Or use the CLI:
-
-```bash
-zibby start ticket-triage --port 8080
-```

package/docs/get-started/deploy.md

@@ -1,75 +0,0 @@
----
-sidebar_position: 4
-title: 4. Deploy to cloud
-pagination_prev: get-started/run-locally
-pagination_next: get-started/trigger-and-logs
----
-
-# Ship an agent to Zibby Cloud
-
-```bash
-zibby agent deploy my-agent
-```
-
-If you have multiple projects, the CLI prompts you to pick one. On success it prints a UUID:
-
-```
-✔ Deployed my-agent (v1)
-✔ Bundle ready (78s) — runtime npm install eliminated
-
-  UUID:        2b1ea07f-3ede-4bfd-a51d-431f0bab008e
-
-  Next steps:
-    zibby agent run my-agent         Run locally
-    zibby agent trigger 2b1ea07f-...    Run in cloud
-    zibby agent list                    View all agents
-```
-
-The UUID is **canonical** — it never changes once issued. All cloud commands (`trigger`, `logs`, `download`, `delete`) take that UUID as their identifier. The CLI caches it in `.zibby/workflows/my-agent/.zibby-deploy.json` so you don't have to remember it. Commit that file to git; collaborators share the same canonical reference.
-
-## What deploy actually does
-
-Two phases:
-
-1. **Source upload** — your agent folder (sources only, no `node_modules`) is uploaded as a JSON payload to S3 via a presigned URL. The CLI also resolves your `.zibby.config.mjs` (if present at project root) and ships it inside the bundle as `zibby.config.json`, so the cloud sees the same config as your local runs.
-2. **Bundle build (Heroku-style)** — a CodeBuild job downloads the sources, runs `npm install --omit=dev`, packages the result as a tarball, and uploads it to S3. The tarball is what each cloud execution downloads at trigger time, so there's **no `npm install` at runtime** — agents boot in seconds.
-
-You'll see a live spinner with the active build step:
-
-```
-⠹ Building bundle on Zibby Cloud... [3/4] Installing dependencies — 32s
-```
-
-Pass `--verbose` if you want to see raw CodeBuild logs.
-
-## Re-deploys keep the same UUID
-
-Once an agent has a UUID, every subsequent `deploy` increments the version but keeps the UUID stable:
-
-```
-v1 → v2 → v3 → ...    (same UUID, same trigger URL)
-```
-
-So your `curl` calls and CI integrations don't break across deploys.
-
-## Naming vs. UUIDs
-
-A clean mental model:
-
-- **Agent folder name** (`my-agent`) is *local* — used by `agent new`, `start`, `deploy`. It's just a directory name.
-- **UUID** (`2b1ea07f-...`) is *canonical* — used by `trigger`, `logs`, `download`, `delete`. Stable across deploys.
-
-`agent list` shows both:
-
-```
-┌─────────────────────────────────────┬──────────────┬──────────┬─────┐
-│ UUID                                │ Name         │ Project  │ Ver │
-├─────────────────────────────────────┼──────────────┼──────────┼─────┤
-│ 2b1ea07f-3ede-4bfd-a51d-431f0bab008e│ my-agent  │ Zibby UI │ 3   │
-│ -                                   │ scratchpad   │ -        │ -   │
-└─────────────────────────────────────┴──────────────┴──────────┴─────┘
-```
-
-`-` in the UUID column means a local-only agent that hasn't been deployed yet.
-
-→ Next: [Trigger & tail logs](./trigger-and-logs)