zilmate 1.0.0

package/.env.example

@@ -0,0 +1,14 @@
+AI_GATEWAY_API_KEY=
+COMPOSIO_API_KEY=
+ZILMATE_USER_ID=
+TAVILY_API_KEY=
+UPSTASH_REDIS_REST_URL=
+UPSTASH_REDIS_REST_TOKEN=
+ZILO_MANAGER_MODEL=minimax/minimax-m3
+ZILO_HELP_MODEL=alibaba/qwen3.7-plus
+ZILO_POST_MODEL=alibaba/qwen3.7-plus
+ZILO_IMAGE_DEFAULT_PROVIDER=openai
+ZILO_IMAGE_OPENAI_MODEL=openai/gpt-image-2
+ZILO_IMAGE_GEMINI_MODEL=google/gemini-3-pro-image
+# Backward-compatible legacy override for Gemini/default image model.
+ZILO_IMAGE_MODEL=

package/README.md

@@ -0,0 +1,326 @@
+# ZilMate
+
+ZilMate is a CLI-first general assistant with deep built-in ZiloShift expertise. It can chat, answer support questions, draft posts, research docs/web sources, generate image assets, and use Composio for external app tools such as GitHub, Gmail, Slack, Notion, Stripe, and Supabase.
+
+The GitHub project can remain `zilo-manager`, but the installable npm package and command are both `zilmate`.
+
+## Install ZilMate
+
+### Published npm package
+
+After the package is published to npm:
+
+```powershell
+npm install -g zilmate
+zilmate setup
+zilmate --help
+```
+
+### GitHub/private install
+
+Before npm publishing, install directly from the GitHub repo:
+
+```powershell
+npm install -g github:zester4/zilo-manager
+zilmate setup
+zilmate --help
+```
+
+### Windows installer helper
+
+From PowerShell, the helper can install from GitHub by default:
+
+```powershell
+iwr https://raw.githubusercontent.com/zester4/zilo-manager/main/install.ps1 | iex
+```
+
+The installer runs the full first-use flow:
+
+1. Installs ZilMate globally.
+2. Runs `zilmate setup` to collect `AI_GATEWAY_API_KEY`, optional `COMPOSIO_API_KEY`, optional `TAVILY_API_KEY`, and optional Redis keys.
+3. Lets users skip Composio, Tavily, and Redis keys.
+4. Runs `zilmate ping` to verify the key.
+5. Starts `zilmate talk`.
+
+To install without setup:
+
+```powershell
+iex "& { $((iwr -UseBasicParsing https://raw.githubusercontent.com/zester4/zilo-manager/main/install.ps1).Content) } -NoSetup"
+```
+
+To skip ping or chat startup:
+
+```powershell
+iex "& { $((iwr -UseBasicParsing https://raw.githubusercontent.com/zester4/zilo-manager/main/install.ps1).Content) } -NoPing -NoTalk"
+```
+
+To install from npm after publishing:
+
+```powershell
+iex "& { $((iwr -UseBasicParsing https://raw.githubusercontent.com/zester4/zilo-manager/main/install.ps1).Content) } -Source npm"
+```
+
+The helper checks for Node/npm, runs `npm install -g`, prints `zilmate --help`, starts setup unless `-NoSetup` is passed, verifies auth unless `-NoPing` is passed, and starts chat unless `-NoTalk` is passed.
+
+## Setup
+
+1. Install dependencies:
+
+```powershell
+npm install
+```
+
+2. Create `.env` from `.env.example`:
+
+The easiest path is:
+
+```powershell
+zilmate setup
+```
+
+It asks for `AI_GATEWAY_API_KEY`, optionally asks for `COMPOSIO_API_KEY`, `TAVILY_API_KEY`, and Upstash Redis keys, then writes a local `.env`. Composio, Tavily, and Redis can be skipped.
+
+You can also create `.env` manually:
+
+```env
+AI_GATEWAY_API_KEY=your_vercel_ai_gateway_key
+COMPOSIO_API_KEY=your_composio_key
+ZILMATE_USER_ID=zilmate-generated-local-user-id
+TAVILY_API_KEY=your_tavily_key
+UPSTASH_REDIS_REST_URL=
+UPSTASH_REDIS_REST_TOKEN=
+ZILO_MANAGER_MODEL=minimax/minimax-m3
+ZILO_HELP_MODEL=alibaba/qwen3.7-plus
+ZILO_POST_MODEL=alibaba/qwen3.7-plus
+ZILO_IMAGE_DEFAULT_PROVIDER=openai
+ZILO_IMAGE_OPENAI_MODEL=openai/gpt-image-2
+ZILO_IMAGE_GEMINI_MODEL=google/gemini-3-pro-image
+ZILO_IMAGE_MODEL=
+```
+
+Composio is optional. If `COMPOSIO_API_KEY` is set, ZilMate creates a stable local `ZILMATE_USER_ID`, reuses Composio sessions per chat session, and lets Composio manage app auth links and connected accounts.
+
+Redis is optional. If `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` are set, chat turns, scratchpads, and Composio session ids use Redis. If they are missing, ZilMate falls back to local files under `.zilo-manager/`.
+
+## Development Commands
+
+Use these while working inside the project folder:
+
+```powershell
+npm run build
+npm run zilmate -- --help
+npm run zilmate -- setup
+npm run zilmate -- doctor
+npm run zilmate -- config
+npm run zilmate -- models
+npm run zilmate -- apps status
+npm run zilmate -- triggers listen
+npm run zilmate -- triggers types github
+npm run zilmate -- triggers list
+npm run zilmate -- remember "Prefers concise support replies"
+npm run zilmate -- recall support
+npm run zilmate -- memory list
+npm run zilmate -- talk
+npm run zilmate -- talk --session launch
+npm run zilmate -- help "why can't a worker apply?"
+npm run zilmate -- post "WhatsApp status for workers in Accra"
+npm run zilmate -- research "Vercel AI SDK ToolLoopAgent"
+npm run zilmate -- image --model openai --size 1024x1024 "ZiloShift launch poster for Ghana workers"
+npm run zilmate -- image --model gemini "ZiloShift launch poster for Ghana workers"
+npm run zilmate -- manager "Create a plan for helping venues post shifts"
+```
+
+Shortcut:
+
+```powershell
+npm run talk
+npm run doctor
+```
+
+## Global CLI
+
+For local development, link the command from this folder:
+
+```powershell
+npm run build
+npm link
+```
+
+Then use ZilMate directly:
+
+```powershell
+zilmate --help
+zilmate setup
+zilmate doctor
+zilmate env check
+zilmate config
+zilmate talk
+zilmate ping
+zilmate models
+zilmate apps status
+zilmate triggers listen
+zilmate triggers types github
+zilmate triggers create GITHUB_BRANCH_CREATED_TRIGGER --dry-run --owner zester4 --repo zilo-manager
+zilmate triggers create GITHUB_COMMIT_EVENT --owner zester4 --repo zilo-manager
+zilmate triggers list
+zilmate remember "Use a warm but concise support tone"
+zilmate recall support
+zilmate memory list
+zilmate help "worker cannot see shifts"
+zilmate image --model openai --size 1024x1024 "ZiloShift launch poster"
+```
+
+## Server SDK
+
+ZilMate can also be used as a server-side SDK inside apps, dashboards, API routes, and background jobs. The SDK is server-only because it uses API keys, local/Redis memory, Tavily, Composio, and AI Gateway credentials.
+
+```ts
+import { createZilMate } from 'zilmate/server';
+
+const zilmate = createZilMate({
+  sessionId: 'support-ticket-123',
+});
+
+const result = await zilmate.chat({
+  message: 'Plan my day, then help me draft a ZiloShift worker update.',
+});
+
+console.log(result.text);
+```
+
+In Next.js, call ZilMate from an API route or server action, then connect your UI to that endpoint:
+
+```ts
+// app/api/zilmate/route.ts
+import { createZilMate } from 'zilmate/server';
+
+export async function POST(req: Request) {
+  const { message, sessionId } = await req.json();
+  const zilmate = createZilMate({ sessionId });
+  const result = await zilmate.chat({ message });
+
+  return Response.json(result);
+}
+```
+
+Available SDK methods:
+
+- `chat({ message })`: general personal assistant backed by the manager agent.
+- `manager({ message | prompt })`: explicit manager orchestration.
+- `help({ question | message })`: fast ZiloShift troubleshooting.
+- `guide({ message })`: ZiloShift workflow conversation.
+- `post({ prompt })`: WhatsApp/status/social copy.
+- `research({ query | message })`: local docs and web research.
+- `image({ prompt, provider, size, outputDir })`: image generation.
+- `remember({ text, tags })`, `recall({ query, limit })`, `listMemories()`, `forget(id)`, `clearMemories()`: durable memory helpers.
+
+For UI integrations, pass `onProgress` to render agent/tool progress and `confirm` to approve or block external write-like Composio actions.
+
+## Command Shape
+
+- `talk`: persistent interactive chat with the main manager agent. This is the best mode for normal use and renders rich terminal Markdown.
+- `manager`: one-shot manager orchestration. It can delegate to subagents and use scratchpad tools.
+- `doctor`: check local setup, required/optional keys, Node version, memory folder, Redis completeness, and optional live Gateway/Composio status with `--live`.
+- `env check`: environment-readiness alias for `doctor`.
+- `config`: sanitized config summary without secrets.
+- `remember`: save durable long-term memory.
+- `recall`: search durable long-term memory.
+- `forget`: delete one memory by id, or use `--all`.
+- `memory list`: list saved durable memories.
+- `apps status`: show whether Composio is configured, the local `ZILMATE_USER_ID`, the current Composio session id, and connected/available toolkit status when the SDK can fetch it.
+- `triggers listen`: stream Composio trigger events into the terminal until Ctrl+C.
+- `triggers types [toolkit]`: list available trigger types, optionally for one toolkit.
+- `triggers info <trigger>`: show trigger config and payload schemas.
+- `triggers create <trigger> --flag value`: create a trigger instance; unknown flags become trigger config.
+- `triggers list`: list trigger instances.
+- `help`: fast troubleshooting and app guidance.
+- `chat`: one-shot natural dialogue about ZiloShift workflows.
+- `post`: WhatsApp/status/social copy generation.
+- `research`: local docs, allowlisted docs, Tavily search/extract/map/crawl/deep research, and sourced summaries.
+- `image`: Gateway image generation that saves files under `outputs/images/`. Use `--model openai|chatgpt|gemini` and optionally `--size 1024x1024` for OpenAI.
+- `models`: selected models, Gateway availability warnings, and active memory backend.
+- `ping`: tiny Gateway text call to verify auth.
+- `setup`: interactive `.env` setup for the required AI Gateway key, optional Composio external app tools, optional Tavily search, optional Redis memory, and model defaults.
+
+## Agent Architecture
+
+ZilMate uses a manager agent that delegates to focused subagents and external tools:
+
+- Quick Help: short troubleshooting and app usage guidance.
+- Chat: broader ZiloShift workflow conversation.
+- Post: launch messages, WhatsApp statuses, captions, and outreach copy.
+- Research: local Zilo docs first, then external docs/web research when needed.
+- Image: image generation through Gateway image models.
+- Composio: external app discovery, auth links, schemas, and execution, attached only to the manager.
+- Memory: durable ZilMate facts and preferences saved locally or in Redis, available through CLI commands and manager tools.
+
+Local ZiloShift docs live under `src/doc/`. ZilMate reads them on demand through dedicated tools instead of dumping all docs into every prompt. The manager prefers these local docs for ZiloShift support, worker, venue, payment, verification, SMS, and dispute questions.
+
+## External Apps With Composio
+
+Run setup and add a Composio key:
+
+```powershell
+zilmate setup
+zilmate apps status
+```
+
+In `zilmate talk`, ask for the external task naturally. If an account is not connected yet, ZilMate uses Composio connection tools and prints the connect link returned by Composio. ZilMate does not implement custom OAuth flows.
+
+Read/search/schema/auth-link tools can run without confirmation. Write-like external app actions such as create, update, delete, send, post, publish, invite, transfer, charge, refund, cancel, approve, revoke, workbench, or bash require `Proceed? (y/N)` in the terminal. In noninteractive mode, write-like actions are blocked.
+
+## Trigger Events
+
+For live terminal events, use Composio trigger listening:
+
+```powershell
+zilmate triggers types github
+zilmate triggers create GITHUB_COMMIT_EVENT --owner zester4 --repo zilo-manager
+zilmate triggers listen
+```
+
+`listen` streams matching trigger events until Ctrl+C. Use filters when needed:
+
+```powershell
+zilmate triggers listen --toolkit gmail
+zilmate triggers listen --trigger ti_abc123
+zilmate triggers listen --trigger-slug GMAIL_NEW_EMAIL_EVENT --once
+```
+
+This is terminal-local. For persistent public callbacks, use webhook/tunnel support later.
+
+The manager agent also has trigger tools. In `zilmate talk`, you can ask:
+
+```text
+show me GitHub trigger types
+prepare a branch-created trigger for zester4/zilo-manager
+create that trigger
+```
+
+ZilMate should discover current trigger slugs first, inspect the trigger schema, prefer a dry-run payload, and ask for confirmation before creating a real trigger.
+
+## Model Notes
+
+- Manager/orchestration default: `minimax/minimax-m3`.
+- Recommended help/post override: `alibaba/qwen3.7-plus` in `.env`.
+- If help/post env vars are blank, ZilMate falls back to the internal cheap-model list in `src/config/models.ts`.
+- Default image provider: OpenAI GPT Image 2 via `openai/gpt-image-2` and AI SDK `generateImage`.
+- Alternate image provider: Gemini 3 Pro Image via `google/gemini-3-pro-image` and `generateText` file outputs.
+- GPT-2 is not used for images.
+
+## Research And Memory
+
+- Zilo docs are searched/read locally first for product behavior.
+- Tavily powers web search, URL extraction, site mapping, small capped crawls, and deep research.
+- Web crawling and deep research are intentionally heavier tools and should be used only when local docs/search are not enough.
+- Scratchpads keep intermediate notes outside the main prompt context.
+- Long-term memory stores stable preferences and durable project facts. Use `zilmate remember`, `zilmate recall`, `zilmate forget`, and `zilmate memory list`.
+- `zilmate talk` automatically recalls relevant long-term memories for each message.
+- Redis is optional; local file memory is the fallback.
+- `zilmate setup` creates or updates the local `.env` used by the CLI.
+
+## Safety Notes
+
+ZilMate can guide, research, draft, generate assets, and run approved external app actions through Composio. It should not claim that live external or ZiloShift data changed unless a tool result confirms it.
+
+Before adding real actions around payments, identity, SMS, users, or admin operations, add stronger permission levels, confirmation gates, audit logs, and behavioral evals.

package/agent-docs.md

@@ -0,0 +1,264 @@
+Building Subagents in the Vercel AI SDK v6
+11 min read
+·
+Josh
+Josh
+Copy article
+
+https://upstash.com/blog/subagents-in-ai-sdk-v6
+A subagent in the AI SDK v6 is one agent wrapped inside a tool() so another agent can call it. The parent agent treats the subagent like any other tool: it sends a prompt, gets back text, and decides what to do next.
+
+I find them to be the single most useful pattern to avoid context bloat. No matter how large their task or own context load is, they only return the most important information from their process back to the main agent.
+
+Subagents take care of context-intensive tasks (e.g. research)
+Subagents take care of context-intensive tasks (e.g. research)
+
+The new v6 ToolLoopAgent
+Before v6, building a multi-agent setup meant chaining generateText calls and passing messages between them. The functions to generate or stream text were independant primitives:
+
+In v5, generateText and streamText are primitives
+In v5, generateText and streamText are primitives
+
+In v6, an agent is its own class we can now call functions on. We define it once with a model, instructions, and tools, then call generate or stream on it:
+
+New: tools, prompts etc. move to a single class
+New: tools, prompts etc. move to a single class
+
+The class is ToolLoopAgent. The name describes what it does: it runs the model, executes any tool calls, feeds the results back, and loops until a stop condition fires.
+
+
+import { anthropic } from "@ai-sdk/anthropic";
+import { stepCountIs, ToolLoopAgent } from "ai";
+ 
+const agent = new ToolLoopAgent({
+  model: anthropic("claude-sonnet-4-6"),
+  instructions: "You are a research agent. Answer the task autonomously.",
+  tools: {
+    /* ... */
+  },
+  stopWhen: stepCountIs(10),
+});
+ 
+const result = await agent.generate({ prompt: "Summarize the latest on X." });
+console.log(result.text);
+A subagent is just a tool
+A subagent is a ToolLoopAgent that a parent agent calls through a tool(). The tool's execute function runs the subagent and returns its text.
+
+
+import { anthropic } from "@ai-sdk/anthropic";
+import { stepCountIs, tool, ToolLoopAgent } from "ai";
+import { z } from "zod";
+ 
+const researchSubagent = new ToolLoopAgent({
+  model: anthropic("claude-sonnet-4-6"),
+  instructions: "You are a focused research subagent. Return only a summary.",
+  stopWhen: stepCountIs(10),
+});
+ 
+const researchTool = tool({
+  description: "Delegate a research task to a subagent.",
+  inputSchema: z.object({ prompt: z.string() }),
+  execute: async ({ prompt }, { abortSignal }) => {
+    const result = await researchSubagent.generate({ prompt, abortSignal });
+    return result.text;
+  },
+});
+ 
+const parentAgent = new ToolLoopAgent({
+  model: anthropic("claude-sonnet-4-6"),
+  instructions: "Delegate research, then synthesize an answer.",
+  tools: { research: researchTool },
+  stopWhen: stepCountIs(10),
+});
+Two details are important here.
+
+First, the tool field is inputSchema, not parameters. Earlier AI SDK versions used parameters; v5 renamed it to inputSchema to align with the Model Context Protocol, and v6 keeps that name.
+
+Second, the execute function takes abortSignal from its second argument and passes it into the subagent. If the parent request is cancelled, that cancellation reaches the subagent too. Without it, a cancelled request leaves subagents running in the background, still using tokens.
+
+Controlling the subagent output
+By default, the parent receives whatever the subagent tool returns. A research subagent might run ten steps and produce a lot of text, and we may not want all of that landing back in the parent's context window.
+
+With toModelOutput, we can decouple what the tool returns from what gets passed into the parent model. It's like a separate parsing step.
+
+
+const researchTool = tool({
+  description: "Delegate a research task to a subagent.",
+  inputSchema: z.object({ prompt: z.string() }),
+  execute: async ({ prompt }, { abortSignal }) => {
+    const result = await researchSubagent.generate({ prompt, abortSignal });
+    return result.text;
+  },
+  toModelOutput: ({ output }) => ({ type: "text", value: output }),
+});
+This way the parent's context stays small while the subagent can consume an almost arbitrary amount of tokens, just bounded by it's context limit. Because either way, it will not bloat our parent.
+
+This patterns is also super useful for keeping the parent's token count low as the number of subagents grows.
+
+Creating a stop condition
+A ToolLoopAgent keeps looping until a StopCondition tells it to stop. The default is stepCountIs(20), so an agent with no stopWhenwill run up to 20 steps:
+
+
+import { anthropic } from "@ai-sdk/anthropic";
+import { hasToolCall, stepCountIs, type StopCondition } from "ai";
+ 
+// custom stop condition
+const stopAfterAnyToolUse: StopCondition<any, any> = ({ steps }) =>
+  steps.some((step) => step.toolCalls.length > 0);
+ 
+const agent = new ToolLoopAgent({
+  model: anthropic("claude-sonnet-4-6"),
+  stopWhen: [stepCountIs(10), hasToolCall("done"), stopAfterAnyToolUse],
+});
+We can pass an array of conditions, and the loop stops when any one of them is true. stepCountIs(n) caps the step count, hasToolCall(name) stops once the agent uses any tool, and a custom function gets the full steps array so we can stop on anything we can compute from it, like a token budget.
+
+By the way, prepareStep runs before every step and lets us change the model, the tools, or the messages for that step:
+
+
+const agent = new ToolLoopAgent({
+  model: anthropic("claude-sonnet-4-6"),
+  tools: { research: researchTool, done: doneTool },
+  prepareStep: ({ stepNumber }) => ({
+    toolChoice: stepNumber > 8 ? { type: "tool", toolName: "done" } : "auto",
+  }),
+});
+This one forces the agent toward a done tool as it nears its step limit, instead of letting it stall.
+
+The isolation problem
+A subagent invocation starts with a fresh context window every time. The subagents docs call context isolation a feature, and for a single delegated task it is. The subagent doesn't load the parent's full history, and the parent shouldn't know about the subagent's intermediate steps.
+
+The isolation goes both ways. But in two cases it kinda gets in the way:
+
+Parallel subagents. The main agent runs three research subagents at once and none of them can see what the others found. If two should avoid duplicating work, there's no way for them to coordinate.
+Separate requests. In serverless, each HTTP request can be a cold start. Anything a subagent held in memory on the last request is gone. The orchestrator on the second request doesn't know what the subagents did on the first request.
+Parallel subagents cannot talk to each other.
+Parallel subagents cannot talk to each other.
+
+Moving the shared state out of process fixes both problems. The official memory docs point at hosted memory services for this, but for short-lived agent state we use Redis. It works with HTTP and the key expiry handles cleanup automatically.
+
+Sharing state across subagents with Redis
+A pattern I really like is a "shared scratchpad". It's one Redis string keyed by the current message id. Each subagent gets two tools: one to read what the others have already written, and one to append its own findings. We pass the same mocked message id to every subagent so they all point at the same key.
+
+
+import { redis } from "@/lib/redis";
+import { anthropic } from "@ai-sdk/anthropic";
+import { stepCountIs, tool, ToolLoopAgent } from "ai";
+import { z } from "zod";
+ 
+function createNoteTools(messageId: string) {
+  return {
+    readNotes: tool({
+      description: "Read what the other subagents have found so far.",
+      inputSchema: z.object({}),
+      execute: async () => {
+        return (await redis.get<string>(`notes:${messageId}`)) ?? "(empty)";
+      },
+    }),
+    appendToNotes: tool({
+      description: "Append your findings to the shared notes.",
+      inputSchema: z.object({ findings: z.string() }),
+      execute: async ({ findings }) => {
+        await redis.append(`notes:${messageId}`, `\n${findings}`);
+        return "Appended.";
+      },
+    }),
+  };
+}
+ 
+// this comes from the ai sdk
+const EXAMPLE_MESSAGE_ID = "example-run-001";
+ 
+const researchSubagent = new ToolLoopAgent({
+  model: anthropic("claude-sonnet-4-6"),
+  instructions: `You are a research subagent. Read your notes to see what others found, then append your research.`,
+  tools: createNoteTools(EXAMPLE_MESSAGE_ID),
+  stopWhen: stepCountIs(10),
+});
+ 
+const parent = new ToolLoopAgent({
+  model: anthropic("claude-sonnet-4-6"),
+  instructions: `Start three research subagents in parallel on these topics: 1. Serverless databases  2. Edge computing  3. AI inference costs.`,
+  tools: {
+    subagent: tool({
+      description: "Run a research subagent on a topic.",
+      inputSchema: z.object({ topic: z.string() }),
+      execute: async ({ topic }, { abortSignal }) => {
+        const result = await researchSubagent.generate({
+          prompt: `Research this topic: ${topic}`,
+          abortSignal,
+        });
+        return result.text;
+      },
+    }),
+    readNotes: createNoteTools(EXAMPLE_MESSAGE_ID).readNotes,
+  },
+  stopWhen: stepCountIs(10),
+});
+ 
+const result = await parent.generate({ prompt: "Start the research." });
+Each subagent runs in isolation but writes into the same Redis string. The parent kicks off the three subagents, and once they finish it calls readNotes itself to pull the full notes before synthesizing. Anthropic's orchestrator-workers pattern is the same shape: a central agent splits the work, workers run it, the central agent synthesizes.
+
+One note: this works because research subtopics are independent. If subagent B needs what subagent A found, we can't fan them out in parallel. We run them in sequence, or have the parent make a second round of calls after reading the first round's results from Redis.
+
+This patterns also allows us to implement a mechanism for the main agent to follow up (e.g. "keep chating") to research subagents. Because they keep their own message history and state, if the main model is unhappy or wants to follow up, we could simply pass the conversation ID into the research agent and it automatically can read and interact with previous notes.
+
+Persisting message history across requests
+The second use of Redis is saving message history. The AI SDK's useChat works with UIMessage[]. We save that array to Redis at the end of a request and load it at the start of the next one.
+
+
+import { Redis } from "@upstash/redis";
+import type { UIMessage } from "ai";
+ 
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+});
+ 
+async function saveHistory(sessionId: string, messages: UIMessage[]) {
+  await redis.set(`chat:${sessionId}`, messages, { ex: 86_400 });
+}
+ 
+async function loadHistory(sessionId: string) {
+  const messages = await redis.get<UIMessage[]>(`chat:${sessionId}`);
+  return messages ?? [];
+}
+Streaming subagent progress to the UI
+If a subagent runs for a while, we want to show the user it is working instead of "freezing" the UI until it finishes. A tool's execute can be an async generator. Each value it yields becomes a partial tool result that the client can render before the final chunk arrives.
+
+
+import { readUIMessageStream, tool } from "ai";
+import { z } from "zod";
+ 
+const streamingResearchTool = tool({
+  description: "Delegate research to a streaming subagent.",
+  inputSchema: z.object({ prompt: z.string() }),
+  async *execute({ prompt }, { abortSignal }) {
+    const result = await researchSubagent.stream({ prompt, abortSignal });
+ 
+    for await (const message of readUIMessageStream({
+      stream: result.toUIMessageStream(),
+    })) {
+      yield message;
+    }
+  },
+});
+The streamed result exposes a UI message stream. The readUIMessageStream helper turns that into an async iterable, where each value is the full message built up so far. The generator yields each update, and the client can now render the subagent's progress in real time.
+
+When to use a subagent and when not to
+Subagents add a layer of complexity. Every level of delegation is another model running its own loop. A single ToolLoopAgent with a good set of tools handles most tasks, and it is cheaper and easier to debug.
+
+But on the other hand, I find subagents to be the single most useful tool to avoid context bloat. By splitting my research and code verification into separate subagents for a project I'm building, the main model's output has become significantly better.
+
+So I'd add a subagent when one of these is true:
+
+Situation	Single agent	Subagent
+One task, a handful of tools	Cheaper, easier to debug. Wins	Overkill
+Work that fans out into independent subtasks	Context bloat	Wins. Run them in parallel, isolate each context.
+One subtask needs a different model or tool set	Awkward to switch mid-loop	Wins. Each subagent has its own model and tools.
+Exploration that would blow the context window	Hits the model's limit or context bloat	Wins. toModelOutput keeps the parent's context smal
+Recap
+A subagent is a ToolLoopAgent wrapped in a tool(); the parent calls it like any tool.
+Pass the abortSignal through so cancellation can reach the subagent.
+Subagent contexts are isolated by design
+With a shared Redis string keyed by a mocked message id, we can give parallel subagents a "scratchpad", and save UIMessage[] to Redis to persist message history.
+I'd add subagents when work is parallel, needs isolated context, or needs a different model; otherwise a single agent is the right default.

package/dist/agents/chat.agent.d.ts

@@ -0,0 +1,30 @@
+import { ToolLoopAgent } from 'ai';
+export declare function createChatAgent(): ToolLoopAgent<never, {
+    appKnowledge: import("ai").Tool<{
+        key: "agent-docs" | "readme";
+    }, string>;
+    listZiloDocs: import("ai").Tool<Record<string, never>, {
+        key: string;
+        title: string;
+        description: string;
+    }[]>;
+    readZiloDoc: import("ai").Tool<{
+        key: string;
+        maxChars?: number | undefined;
+    }, {
+        key: string;
+        title: string;
+        description: string;
+        content: string;
+    }>;
+    searchZiloDocs: import("ai").Tool<{
+        query: string;
+        maxResults?: number | undefined;
+    }, {
+        key: string;
+        title: string;
+        description: string;
+        snippet: string;
+    }[]>;
+}, never>;
+//# sourceMappingURL=chat.agent.d.ts.map

package/dist/agents/chat.agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.agent.d.ts","sourceRoot":"","sources":["../../src/agents/chat.agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,aAAa,EAAE,MAAM,IAAI,CAAC;AAKhD,wBAAgB,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;UAU9B"}

package/dist/agents/chat.agent.js

@@ -0,0 +1,16 @@
+import { stepCountIs, ToolLoopAgent } from 'ai';
+import { models } from '../config/models.js';
+import { appKnowledgeTool } from '../tools/app-knowledge.tool.js';
+import { ziloDocsTools } from '../tools/zilo-docs.tool.js';
+export function createChatAgent() {
+    return new ToolLoopAgent({
+        model: models.chat,
+        instructions: 'You are the ZiloShift conversational app guide. Explain workflows for workers, venues, admin operations, payments, disputes, shifts, onboarding, and launch tasks in a calm practical tone. Use local ZiloShift docs on demand for accurate product behavior instead of guessing. Keep answers practical and do not dump long docs into the response.',
+        tools: {
+            ...ziloDocsTools,
+            appKnowledge: appKnowledgeTool,
+        },
+        stopWhen: stepCountIs(6),
+    });
+}
+//# sourceMappingURL=chat.agent.js.map

package/dist/agents/chat.agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.agent.js","sourceRoot":"","sources":["../../src/agents/chat.agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,MAAM,UAAU,eAAe;IAC7B,OAAO,IAAI,aAAa,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC,IAAI;QAClB,YAAY,EAAE,uVAAuV;QACrW,KAAK,EAAE;YACL,GAAG,aAAa;YAChB,YAAY,EAAE,gBAAgB;SAC/B;QACD,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;KACzB,CAAC,CAAC;AACL,CAAC"}