stagent 0.5.0 → 0.6.0

package/docs/use-cases/solo-founder.md

@@ -0,0 +1,75 @@
+---
+title: "Solo Founder Use Case"
+category: "use-case"
+lastUpdated: "2026-03-31"
+---
+
+# Solo Founder
+
+You are one person running a business. You handle product, marketing, support, ops, and finance — often in the same afternoon. Stagent lets you deploy AI agents as your team, with the governance and cost controls a business requires.
+
+## How Stagent Maps to Your Business
+
+| Business Concept | Stagent Feature | What It Does |
+|-----------------|----------------|--------------|
+| Business units | **Projects** | Organize work by product line, client, or initiative. Each project scopes tasks, documents, and agent activity |
+| Business processes | **Workflows** | Multi-step automations with 6 patterns — sequence, parallel, loop, planner-executor, checkpoint, swarm |
+| AI team members | **Profiles** | 21 specialist agents (researcher, writer, code reviewer, DevOps, etc.) with consistent instructions and tool policies |
+| Recurring ops | **Schedules** | Automated agent execution on intervals or cron — content publishing, report generation, monitoring sweeps |
+| Business spend | **Cost & Usage** | Per-task, per-provider spend tracking with budget guardrails to prevent surprise bills |
+| Oversight | **Inbox & Permissions** | Approve high-stakes actions, answer agent questions, and maintain an audit trail for every decision |
+
+## Example Scenarios
+
+### 1. Content Pipeline
+
+**Goal:** Publish three blog posts per week without writing each one from scratch.
+
+**Setup:**
+- Create a "Content" project with your brand guidelines as a linked document
+- Use the **document-writer** profile for drafting and the **researcher** profile for topic research
+- Build a **sequence workflow**: Research trending topics → Draft outline → Write full post → Format for publishing
+
+**Schedule:** Run the research step every Monday and Thursday at 9 AM. The workflow pauses at a checkpoint for your review before the agent publishes.
+
+**Cost control:** Set a per-task budget of $2.00 to prevent runaway generation. The cost dashboard shows exactly how much each post costs to produce.
+
+### 2. Lead Research
+
+**Goal:** Build a qualified prospect list from public data every week.
+
+**Setup:**
+- Create a "Sales Pipeline" project
+- Use the **researcher** profile with browser tools enabled for web research
+- Build a **parallel workflow**: Fork into 3-5 industry verticals → Each branch researches companies and contacts → Join step synthesizes into a ranked list
+
+**Schedule:** Run every Monday morning. Results land in the project as a document you can review and export.
+
+**Governance:** The researcher profile has read-only tool permissions — it can browse and read, but cannot modify files or run shell commands. Browser automation requests route through the inbox for approval.
+
+### 3. Support Triage
+
+**Goal:** Classify incoming support emails and draft responses without manual sorting.
+
+**Setup:**
+- Create a "Customer Support" project
+- Upload your FAQ and standard operating procedures as reference documents
+- Use a custom **support-triage** profile that references these documents
+- Build a **loop workflow**: The agent processes support items iteratively, classifying priority and drafting responses, until the queue is empty or it hits the iteration limit
+
+**Schedule:** Run every 2 hours during business hours with an expiry at end of day. The agent draft responses wait in the inbox for your approval before sending.
+
+**Audit trail:** Every classification decision and draft response is logged in the monitor, so you can review the agent's reasoning and correct patterns over time through the learned context loop.
+
+## Getting Started
+
+```bash
+npx stagent
+```
+
+1. Create your first project for one of the scenarios above
+2. Browse the profile gallery and assign a specialist to your first task
+3. Run the task and approve tool requests from the inbox
+4. Check the cost dashboard after a few runs to establish your baseline spend
+
+See the [Personal Use Journey](../journeys/personal-use.md) for a step-by-step walkthrough, or [Why Stagent](../why-stagent.md) for the full platform overview.

package/docs/why-stagent.md

@@ -0,0 +1,59 @@
+---
+title: "Why Stagent"
+category: "overview"
+lastUpdated: "2026-03-31"
+---
+
+# Why Stagent
+
+## The Broken AI Agent Stack
+
+AI agents can write code, research markets, draft proposals, and triage support tickets. The raw capability is there. But the stack between "demo" and "daily business operations" is broken in five places — and every solo founder, micro-team, and AI agency hits them.
+
+### Five Gaps
+
+**1. Orchestration gap.** You can run one agent on one task. But real business work is multi-step: research leads, then enrich profiles, then draft outreach, then schedule follow-ups. Stitching agents into reliable sequences, parallel branches, or iterative loops requires custom glue code that nobody wants to maintain.
+
+**2. Strategy-to-execution gap.** Business operators think in projects, processes, and outcomes. Agent tools think in prompts, tokens, and tool calls. There is no shared language between what the business needs and what the agent executes — so operators end up copy-pasting prompts and hoping for the best.
+
+**3. Lifecycle gap.** A task does not end when the agent finishes. It needs scheduling, retry on failure, resume from checkpoints, cost tracking, and audit trails. Most agent frameworks stop at "run once and print output," leaving the entire operational lifecycle to the user.
+
+**4. Trust and governance gap.** Agents that can read files, run shell commands, and call APIs need guardrails. Which tools are allowed? Who approves destructive actions? What happens when the agent asks a question at 2 AM? Without a governance layer, agent use stays limited to low-stakes experiments.
+
+**5. Distribution gap.** Setting up an agent workspace should not require cloning a repo, configuring a build system, and managing a database. Operators need `npx stagent` — one command, zero config, own your data.
+
+## Stagent: AI Business Operating System
+
+Stagent closes all five gaps in a single local-first platform.
+
+**Projects as business units.** Organize work into projects with scoped context and working directories. Each project is a container for tasks, documents, workflows, and agent activity — mapping directly to how you think about your business.
+
+**Profiles as your AI team.** 21 specialist profiles ship out of the box: researcher, code reviewer, document writer, DevOps engineer, and more. Each profile packages instructions, allowed tools, runtime tuning, and MCP configs so you deploy consistent behavior instead of ad-hoc prompts. Create custom profiles or import them from GitHub.
+
+**Workflows as business processes.** Six orchestration patterns — sequence, planner-executor, checkpoint, parallel, loop, and swarm — cover everything from simple task chains to multi-agent research pipelines. Workflow blueprints let you template common processes and spin them up with a form.
+
+**Schedules as recurring operations.** Human-friendly intervals (`5m`, `2h`, `1d`) or cron expressions drive automated agent execution. Each firing creates a governed task through the same pipeline, with pause/resume and expiry controls.
+
+**Governance as a business benefit.** Tool permissions, inbox approvals, audit trails, and budget guardrails are not overhead — they are what make it safe to let agents handle real work. Permission presets (read-only, git-safe, full-auto) let you dial trust up or down per profile.
+
+**Cost visibility as financial control.** Provider-normalized metering tracks token usage and spend per task, per model, per provider. Budget guardrails prevent surprise bills. The cost dashboard gives you the same spend visibility you expect from any business tool.
+
+**Multi-provider runtime.** Claude Code and OpenAI Codex App Server run behind one shared registry. Switch providers per task, per schedule, or per workflow step — without changing anything else.
+
+## Who It's For
+
+**Solo founders** who need to run content pipelines, lead research, support triage, and other business processes without hiring a team. Stagent's profiles and workflows replace the coordination overhead of managing multiple tools and prompts.
+
+**Micro-teams (2-10 people)** who want governed AI operations without building internal tooling. Projects organize workstreams, profiles standardize agent behavior across team members, and the inbox keeps a human in the loop for high-stakes decisions.
+
+**AI agencies** deploying agent workflows for clients. Multi-project support maps to client portfolios, profiles customize per vertical, and workflow blueprints package repeatable service offerings. Cost tracking provides per-client spend visibility.
+
+## Get Started
+
+Install and run your first task in under a minute:
+
+```bash
+npx stagent
+```
+
+See the [Getting Started guide](./getting-started.md) for configuration details, or explore the [User Journeys](./index.md#user-journeys) for guided walkthroughs by experience level.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stagent",
-  "version": "0.5.0",
-  "description": "Governed AI agent workspace for supervised local execution, workflows, documents, and provider runtimes.",
+  "version": "0.6.0",
+  "description": "AI Business Operating System — run your business with AI agents. Local-first, multi-provider, governed.",
   "keywords": [
     "ai",
     "agents",
@@ -11,7 +11,12 @@
     "openai",
     "codex",
     "nextjs",
-    "local-first"
+    "local-first",
+    "business",
+    "operating-system",
+    "orchestration",
+    "solo-founder",
+    "ai-business"
   ],
   "license": "Apache-2.0",
   "type": "module",
@@ -58,6 +63,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.71",
+    "@anthropic-ai/sdk": "^0.80.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -80,6 +86,7 @@
     "next": "^16",
     "next-themes": "^0.4.6",
     "open": "^10",
+    "openai": "^6.33.0",
     "pdf-parse": "^2.4.5",
     "radix-ui": "^1.4.3",
     "react": "^19",

package/src/app/api/channels/[id]/route.ts

@@ -0,0 +1,103 @@
+import { NextRequest, NextResponse } from "next/server";
+import { db } from "@/lib/db";
+import { channelConfigs } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+
+  const [channel] = await db
+    .select()
+    .from(channelConfigs)
+    .where(eq(channelConfigs.id, id));
+
+  if (!channel) {
+    return NextResponse.json({ error: "Channel not found" }, { status: 404 });
+  }
+
+  return NextResponse.json(channel);
+}
+
+export async function PATCH(
+  req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const body = await req.json();
+  const { name, config, status, direction } = body as {
+    name?: string;
+    config?: Record<string, unknown>;
+    status?: "active" | "disabled";
+    direction?: "outbound" | "bidirectional";
+  };
+
+  const [channel] = await db
+    .select()
+    .from(channelConfigs)
+    .where(eq(channelConfigs.id, id));
+
+  if (!channel) {
+    return NextResponse.json({ error: "Channel not found" }, { status: 404 });
+  }
+
+  const now = new Date();
+  const updates: Record<string, unknown> = { updatedAt: now };
+
+  if (name !== undefined) {
+    if (!name.trim()) {
+      return NextResponse.json({ error: "Name cannot be empty" }, { status: 400 });
+    }
+    updates.name = name.trim();
+  }
+
+  if (config !== undefined) {
+    updates.config = JSON.stringify(config);
+    updates.testStatus = "untested"; // Reset test status when config changes
+  }
+
+  if (status !== undefined) {
+    if (!["active", "disabled"].includes(status)) {
+      return NextResponse.json({ error: "Invalid status" }, { status: 400 });
+    }
+    updates.status = status;
+  }
+
+  if (direction !== undefined) {
+    if (!["outbound", "bidirectional"].includes(direction)) {
+      return NextResponse.json({ error: "Invalid direction" }, { status: 400 });
+    }
+    updates.direction = direction;
+  }
+
+  await db.update(channelConfigs).set(updates).where(eq(channelConfigs.id, id));
+
+  const [updated] = await db
+    .select()
+    .from(channelConfigs)
+    .where(eq(channelConfigs.id, id));
+
+  return NextResponse.json(updated);
+}
+
+export async function DELETE(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+
+  const [channel] = await db
+    .select()
+    .from(channelConfigs)
+    .where(eq(channelConfigs.id, id));
+
+  if (!channel) {
+    return NextResponse.json({ error: "Channel not found" }, { status: 404 });
+  }
+
+  await db.delete(channelConfigs).where(eq(channelConfigs.id, id));
+
+  return NextResponse.json({ deleted: true });
+}

package/src/app/api/channels/[id]/test/route.ts

@@ -0,0 +1,52 @@
+import { NextRequest, NextResponse } from "next/server";
+import { db } from "@/lib/db";
+import { channelConfigs } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import { getChannelAdapter } from "@/lib/channels/registry";
+
+export async function POST(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+
+  const [channel] = await db
+    .select()
+    .from(channelConfigs)
+    .where(eq(channelConfigs.id, id));
+
+  if (!channel) {
+    return NextResponse.json({ error: "Channel not found" }, { status: 404 });
+  }
+
+  let parsedConfig: Record<string, unknown>;
+  try {
+    parsedConfig = JSON.parse(channel.config) as Record<string, unknown>;
+  } catch {
+    return NextResponse.json({ error: "Invalid channel config JSON" }, { status: 500 });
+  }
+
+  try {
+    const adapter = getChannelAdapter(channel.channelType);
+    const result = await adapter.testConnection(parsedConfig);
+
+    const now = new Date();
+    await db
+      .update(channelConfigs)
+      .set({
+        testStatus: result.ok ? "ok" : "failed",
+        updatedAt: now,
+      })
+      .where(eq(channelConfigs.id, id));
+
+    return NextResponse.json({
+      testStatus: result.ok ? "ok" : "failed",
+      error: result.error,
+    });
+  } catch (err) {
+    return NextResponse.json(
+      { testStatus: "failed", error: err instanceof Error ? err.message : String(err) },
+      { status: 500 }
+    );
+  }
+}

package/src/app/api/channels/inbound/slack/route.ts

@@ -0,0 +1,109 @@
+import { NextRequest, NextResponse } from "next/server";
+import { db } from "@/lib/db";
+import { channelConfigs } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import { slackAdapter } from "@/lib/channels/slack-adapter";
+import { handleInboundMessage } from "@/lib/channels/gateway";
+
+/**
+ * POST /api/channels/inbound/slack?configId=xxx
+ *
+ * Receives Slack Events API callbacks.
+ * Handles:
+ * - url_verification challenge (required during Slack app setup)
+ * - event_callback with message events
+ *
+ * IMPORTANT: Slack requires a 200 response within 3 seconds.
+ * We respond immediately and process the message asynchronously.
+ */
+export async function POST(req: NextRequest) {
+  const configId = req.nextUrl.searchParams.get("configId");
+
+  // Read raw body for signature verification
+  const rawBody = await req.text();
+  let body: SlackPayload;
+  try {
+    body = JSON.parse(rawBody) as SlackPayload;
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+
+  // Handle URL verification challenge (no configId needed)
+  if (body.type === "url_verification") {
+    return NextResponse.json({ challenge: body.challenge });
+  }
+
+  if (!configId) {
+    return NextResponse.json({ error: "Missing configId" }, { status: 400 });
+  }
+
+  // Fetch channel config
+  const config = db
+    .select()
+    .from(channelConfigs)
+    .where(eq(channelConfigs.id, configId))
+    .get();
+
+  if (!config) {
+    return NextResponse.json({ error: "Channel not found" }, { status: 404 });
+  }
+
+  // Verify Slack signature
+  let parsedConfig: Record<string, unknown>;
+  try {
+    parsedConfig = JSON.parse(config.config) as Record<string, unknown>;
+  } catch {
+    return NextResponse.json({ error: "Invalid channel config" }, { status: 500 });
+  }
+
+  // Only verify signature if signingSecret is configured
+  if (parsedConfig.signingSecret && slackAdapter.verifySignature) {
+    const headers: Record<string, string> = {};
+    req.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    if (!slackAdapter.verifySignature(rawBody, headers, parsedConfig)) {
+      return NextResponse.json({ error: "Invalid signature" }, { status: 403 });
+    }
+  }
+
+  // Only handle event_callback with message events
+  if (body.type !== "event_callback") {
+    return NextResponse.json({ ok: true });
+  }
+
+  const message = slackAdapter.parseInbound!(body, {});
+  if (!message) {
+    // Not a message event or bot message — acknowledge silently
+    return NextResponse.json({ ok: true });
+  }
+
+  // Process asynchronously — respond 200 immediately (Slack 3-second requirement)
+  handleInboundMessage({
+    channelConfigId: configId,
+    message,
+  }).catch((err) => {
+    console.error(`[slack-inbound] Error handling message for config ${configId}:`, err);
+  });
+
+  return NextResponse.json({ ok: true });
+}
+
+// ── Slack payload types ────────────────────────────────────────────────
+
+interface SlackPayload {
+  type: string;
+  challenge?: string;
+  token?: string;
+  event?: {
+    type: string;
+    text?: string;
+    user?: string;
+    bot_id?: string;
+    subtype?: string;
+    ts?: string;
+    thread_ts?: string;
+    channel?: string;
+  };
+}

package/src/app/api/channels/inbound/telegram/poll/route.ts

@@ -0,0 +1,128 @@
+import { NextRequest, NextResponse } from "next/server";
+import { db } from "@/lib/db";
+import { channelConfigs } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import { telegramAdapter } from "@/lib/channels/telegram-adapter";
+import { handleInboundMessage } from "@/lib/channels/gateway";
+
+/**
+ * POST /api/channels/inbound/telegram/poll?configId=xxx
+ *
+ * Poll Telegram's getUpdates API for pending messages and process them
+ * through the gateway. Use this for local development when Telegram
+ * can't reach localhost via webhooks.
+ *
+ * Returns the number of updates processed.
+ */
+export async function POST(req: NextRequest) {
+  const configId = req.nextUrl.searchParams.get("configId");
+  if (!configId) {
+    return NextResponse.json({ error: "Missing configId" }, { status: 400 });
+  }
+
+  const config = db
+    .select()
+    .from(channelConfigs)
+    .where(eq(channelConfigs.id, configId))
+    .get();
+
+  if (!config) {
+    return NextResponse.json({ error: "Channel not found" }, { status: 404 });
+  }
+
+  let parsedConfig: Record<string, unknown>;
+  try {
+    parsedConfig = JSON.parse(config.config) as Record<string, unknown>;
+  } catch {
+    return NextResponse.json({ error: "Invalid channel config" }, { status: 500 });
+  }
+
+  const botToken = parsedConfig.botToken as string;
+  if (!botToken) {
+    return NextResponse.json({ error: "Missing botToken in config" }, { status: 400 });
+  }
+
+  // Read optional offset from request body
+  const body = await req.json().catch(() => ({})) as { offset?: number };
+
+  // Fetch updates from Telegram
+  const url = `https://api.telegram.org/bot${botToken}/getUpdates`;
+  const params: Record<string, unknown> = { timeout: 0 };
+  if (body.offset) {
+    params.offset = body.offset;
+  }
+
+  let updates: TelegramUpdate[];
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params),
+    });
+    const data = (await res.json()) as { ok: boolean; result: TelegramUpdate[] };
+    if (!data.ok) {
+      return NextResponse.json({ error: "Telegram getUpdates failed" }, { status: 502 });
+    }
+    updates = data.result;
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : "Telegram API error" },
+      { status: 502 }
+    );
+  }
+
+  if (updates.length === 0) {
+    return NextResponse.json({ processed: 0, nextOffset: body.offset ?? null });
+  }
+
+  // Process each update through the gateway
+  let processed = 0;
+  let maxUpdateId = 0;
+
+  for (const update of updates) {
+    if (update.update_id > maxUpdateId) {
+      maxUpdateId = update.update_id;
+    }
+
+    const message = telegramAdapter.parseInbound!(update, {});
+    if (!message || message.isBot) continue;
+
+    // Process sequentially to respect turn locking
+    try {
+      await handleInboundMessage({ channelConfigId: configId, message });
+      processed++;
+    } catch (err) {
+      console.error(`[telegram-poll] Error processing update ${update.update_id}:`, err);
+    }
+  }
+
+  // Acknowledge processed updates so Telegram doesn't return them again
+  if (maxUpdateId > 0) {
+    try {
+      await fetch(`https://api.telegram.org/bot${botToken}/getUpdates`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ offset: maxUpdateId + 1, timeout: 0 }),
+      });
+    } catch {
+      // Non-fatal — updates will be re-processed next poll
+    }
+  }
+
+  return NextResponse.json({
+    processed,
+    total: updates.length,
+    nextOffset: maxUpdateId + 1,
+  });
+}
+
+interface TelegramUpdate {
+  update_id: number;
+  message?: {
+    message_id: number;
+    from?: { id: number; is_bot: boolean; first_name: string };
+    chat: { id: number; type: string };
+    date: number;
+    text?: string;
+  };
+}

package/src/app/api/channels/inbound/telegram/route.ts

@@ -0,0 +1,76 @@
+import { NextRequest, NextResponse } from "next/server";
+import { db } from "@/lib/db";
+import { channelConfigs } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import { telegramAdapter } from "@/lib/channels/telegram-adapter";
+import { handleInboundMessage } from "@/lib/channels/gateway";
+
+/**
+ * POST /api/channels/inbound/telegram?configId=xxx&secret=yyy
+ *
+ * Receives Telegram Bot API webhook updates.
+ * - configId: channel config ID to route to
+ * - secret: shared secret for verification (set during webhook registration)
+ */
+export async function POST(req: NextRequest) {
+  const configId = req.nextUrl.searchParams.get("configId");
+  const secret = req.nextUrl.searchParams.get("secret");
+
+  if (!configId) {
+    return NextResponse.json({ error: "Missing configId" }, { status: 400 });
+  }
+
+  // Fetch channel config
+  const config = db
+    .select()
+    .from(channelConfigs)
+    .where(eq(channelConfigs.id, configId))
+    .get();
+
+  if (!config) {
+    return NextResponse.json({ error: "Channel not found" }, { status: 404 });
+  }
+
+  // Verify secret token
+  let parsedConfig: Record<string, unknown>;
+  try {
+    parsedConfig = JSON.parse(config.config) as Record<string, unknown>;
+  } catch {
+    return NextResponse.json({ error: "Invalid channel config" }, { status: 500 });
+  }
+
+  const expectedSecret = parsedConfig.webhookSecret as string | undefined;
+  if (expectedSecret && secret !== expectedSecret) {
+    return NextResponse.json({ error: "Invalid secret" }, { status: 403 });
+  }
+
+  // Parse the Telegram update
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+  }
+
+  const message = telegramAdapter.parseInbound!(body, {});
+  if (!message) {
+    // Not a text message (e.g., edited message, photo) — acknowledge silently
+    return NextResponse.json({ ok: true });
+  }
+
+  // Skip bot messages to prevent loops
+  if (message.isBot) {
+    return NextResponse.json({ ok: true });
+  }
+
+  // Process asynchronously — respond 200 immediately to Telegram
+  // (Telegram retries if no response within ~60s, but faster is better)
+  handleInboundMessage({
+    channelConfigId: configId,
+    message,
+  }).catch((err) => {
+    console.error(`[telegram-inbound] Error handling message for config ${configId}:`, err);
+  });
+
+  return NextResponse.json({ ok: true });
+}