@agent-native/core 0.132.2 → 0.133.1

package/corpus/templates/factory/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Chat are documented here. Open it any
+time from the command menu (Cmd+K → "What's new").
+
+## 2026-06-23
+
+### Added
+
+- See what's new right inside Chat — a changelog now lives in the command menu (Cmd+K).

package/corpus/templates/factory/DEVELOPING.md

@@ -0,0 +1,185 @@
+# factory - Development Guide
+
+This guide is for development-mode agents editing this app's source code. For app operations and tools, see AGENTS.md.
+
+## Tech Stack
+
+- **Framework:** @agent-native/core + React Router v8 (framework mode)
+- **Frontend:** React 19, Vite, TailwindCSS, shadcn/ui
+- **Routing:** File-based via `flatRoutes()` — SSR shell + client rendering
+- **Backend:** Nitro (via @agent-native/core) — file-based API routing, server plugins, deploy-anywhere presets
+- **State:** SQL-backed (SSE for real-time updates)
+
+## Commands
+
+- **Dev:** `pnpm dev` (Vite dev server with both React Router + Nitro plugins)
+- **Build:** `pnpm build` (React Router build — client + SSR + Nitro server)
+- **Start:** `node .output/server/index.mjs` (production)
+
+## Directory Structure
+
+```
+app/                   # React frontend
+  root.tsx             # HTML shell + global providers
+  entry.client.tsx     # Client hydration entry
+  routes.ts            # Route config — flatRoutes()
+  routes/              # File-based page routes (auto-discovered)
+    _index.tsx         # / (chat page)
+  components/          # UI components
+  hooks/               # React hooks
+  lib/                 # Utilities (cn, etc)
+
+server/                # Nitro API server
+  routes/
+    api/               # Route-only endpoints (uploads, webhooks, OAuth, streaming)
+    [...page].get.ts   # SSR catch-all (delegates to React Router)
+  plugins/             # Server plugins (startup logic)
+  lib/                 # Shared server modules
+
+shared/                # Isomorphic code (imported by both client & server)
+
+actions/               # Shared app operations (defineAction; UI uses action hooks)
+  run.ts               # Script dispatcher
+  *.ts                 # Individual actions (pnpm action <name>)
+
+data/                  # Local development database fallback
+
+react-router.config.ts # React Router framework config
+.agents/skills/        # Agent skills — detailed guidance for each rule
+```
+
+## Framework Basics
+
+**SSR-first framework, CSR-by-default content:** This app uses React Router v8 framework mode with `ssr: true`. But virtually every route renders only an SSR shell (loading spinner + meta tags). Normal app data fetching happens on the client via action hooks. Server-side data fetching is the exception — only used for public pages that need SEO/OG tags.
+
+## Chat-First Shape
+
+The `/` route is the app's primary chat surface. Keep it on
+`AgentChatSurface` unless you are intentionally replacing the whole chat
+experience. The left sidebar owns the durable thread list through
+`useChatThreads`; app-specific screens can be added alongside it as nav items
+when they become useful.
+
+For a headless app that later needs UI, this template is the intended landing
+zone: bring the existing actions over, keep their names stable, and let the chat
+call them before adding extra screens. For a custom agent backend, keep the app
+shell and swap the chat runtime with an `AgentChatRuntime` connector instead of
+rewriting the composer/transcript UI.
+
+## Adding a Page
+
+Create a file in `app/routes/`. The filename determines the URL path:
+
+```
+app/routes/_index.tsx              → /
+app/routes/settings.tsx            → /settings
+app/routes/inbox.tsx               → /inbox
+app/routes/inbox.$threadId.tsx     → /inbox/:threadId
+app/routes/$id.tsx                 → /:id (dynamic param)
+```
+
+Each route file exports a default component, optional `meta()`, and optional `HydrateFallback()`:
+
+```tsx
+import MyPage from "@/pages/MyPage";
+
+export function meta() {
+  return [{ title: "My Page" }];
+}
+
+export function HydrateFallback() {
+  return (
+    <div className="flex items-center justify-center h-screen">
+      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-foreground" />
+    </div>
+  );
+}
+
+export default function MyPageRoute() {
+  return <MyPage />;
+}
+```
+
+**Do NOT fetch data server-side** in route loaders unless the page genuinely needs SEO/OG content. The standard pattern is: SSR renders the shell, client hydrates, and React reads/writes normal app data through actions with `useActionQuery` / `useActionMutation`.
+
+## Adding App Data
+
+Normal app data starts as an action, not a custom route. Add `actions/<verb>-<resource>.ts` with `defineAction`, mark reads with `http: { method: "GET" }`, and call reads/writes from React with `useActionQuery` / `useActionMutation` from `@agent-native/core/client`. This keeps the UI and agent on one contract and lets mutating actions refresh action-backed queries automatically.
+
+## Adding a Route-Only Endpoint
+
+Use `server/routes/api/` only for protocols that cannot be modeled as JSON actions: multipart uploads, streaming/SSE/WebSocket, webhooks, OAuth callbacks/redirects, public SEO/OG endpoints, or binary/static asset serving. Do not add `/api/*` routes for normal CRUD, data queries, or pass-through wrappers around actions; the action endpoint already exists at `/_agent-native/actions/:name`.
+
+Each route-only endpoint still exports a default `defineEventHandler`, but keep shared app logic in actions or server libraries so agent and UI behavior do not fork.
+
+## Adding a Server Plugin
+
+Startup logic (auth, SSE, etc.) lives in `server/plugins/`. Use `defineNitroPlugin` from core:
+
+```ts
+import { defineNitroPlugin } from "@agent-native/core";
+
+export default defineNitroPlugin(async (nitroApp) => {
+  // Runs once at server startup
+});
+```
+
+## Key Imports from `@agent-native/core`
+
+| Import                                       | Purpose                                                                    |
+| -------------------------------------------- | -------------------------------------------------------------------------- |
+| `defineNitroPlugin`                          | Define a server plugin (re-exported from Nitro)                            |
+| `createDefaultSSEHandler`                    | Create SSE endpoint for DB change events (server)                          |
+| `readAppState`, `writeAppState`              | Read/write application state (from `@agent-native/core/application-state`) |
+| `readSetting`, `writeSetting`                | Read/write settings (from `@agent-native/core/settings`)                   |
+| `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)                                   |
+| `sendToAgentChat`                            | Send messages to agent from UI (client-side)                               |
+| `agentChat`                                  | Send messages to agent from scripts (server-side)                          |
+
+## Adding an Action
+
+Create `actions/<verb>-<resource>.ts` with `defineAction`. Run with `pnpm action <name> --id value`; React callers should use `useActionQuery` for GET actions and `useActionMutation` for mutating actions, not a matching `/api/*` wrapper.
+
+**Sending to agent chat from UI:**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client";
+sendToAgentChat({
+  message: "Generate something",
+  context: "...",
+  submit: true,
+});
+```
+
+**Sending to agent chat from scripts:**
+
+```ts
+import { agentChat } from "@agent-native/core";
+agentChat.submit("Generate something");
+```
+
+## Database & Environment Variables
+
+Local development defaults to a SQLite file at `data/app.db`. That local file is for development; containers, previews, and serverless deploys can reset their filesystem. For production/cloud deployment, set `DATABASE_URL` to point to a persistent SQL database. Turso is optional, not required; common choices include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments when available.
+
+Real credential values belong only in local `.env` files, deployment configuration, or registered secrets/settings UI. Never commit, document, log, return, paste, or include real keys, tokens, webhook URLs, signing secrets, or private data in examples; use empty values or obvious placeholders.
+
+When adding app data, define tables with `@agent-native/core/db/schema` helpers and use Drizzle's query builder for reads/writes. Do not import dialect-specific schema helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`, and do not write raw SQL in normal actions or handlers when Drizzle can express the query. Raw SQL belongs in additive migrations, health checks, or carefully scoped maintenance.
+
+| Variable              | Required                        | Description                                                                |
+| --------------------- | ------------------------------- | -------------------------------------------------------------------------- |
+| `DATABASE_URL`        | Production yes, local dev no    | Persistent SQL connection string (local dev default: `file:./data/app.db`) |
+| `DATABASE_AUTH_TOKEN` | Only when the provider needs it | Auth token for providers such as Turso/libSQL                              |
+| `AUTH_DISABLED`       | Optional                        | Set to `true` or `1` to skip login/signup (local dev/preview only)         |
+
+## Extensions (Framework Feature)
+
+The framework provides **Extensions** — mini sandboxed Alpine.js apps that run inside iframes. Extensions let users (or the agent) create interactive widgets, dashboards, and utilities without modifying the app's source code. They appear in the sidebar under an "Extensions" section. (Distinct from LLM tools — the function-calling primitives the agent invokes.)
+
+- **Creating extensions**: Via the sidebar "+" button, agent chat, or `POST /_agent-native/extensions`
+- **API calls**: Extensions use `extensionFetch()` (legacy alias `toolFetch`) which proxies requests through the server with `${keys.NAME}` secret injection
+- **Styling**: Extensions inherit the main app's Tailwind v4 theme automatically
+- **Sharing**: Private by default, shareable with org or specific users (same model as other ownable resources)
+- **Security**: Iframe sandbox + CSP + SSRF protection on the proxy
+
+See the `extensions` skill in `.agents/skills/extensions/SKILL.md` for full implementation details.

package/corpus/templates/factory/README.md

@@ -0,0 +1,64 @@
+# Factory
+
+Factory is the inspectable foundation for building agent factories: work goes
+in one end, governed agent work and shipped changes come out the other, with
+human intervention points you control. It can start with Slack feedback and
+pull-request evidence, then grow to orchestrate product workflows such as
+PRD -> design -> engineering -> release.
+
+## What it does
+
+- Polls a configured Slack channel and records new messages with thread and
+  coverage metadata.
+- Ingests read-only pull-request evidence from the existing ai-services read
+  boundary.
+- Evaluates editable prompt rules with hard structured guards and stores every
+  decision append-only.
+- Lets a human correct a decision, tune a rule, or explicitly approve bounded
+  work from the Factory UI or the generic Agent-Native Slack bot.
+- Starts configured Builder or harness work only through an approval action,
+  deduped by Factory item, and reconciles signed callbacks and provider state.
+- Surfaces missed callbacks, incomplete evidence, and timeouts as explicit
+  states rather than plausible success.
+
+The current implementation is deliberately observe-first and shadow-only.
+Sensitive work remains human-gated: auth/session/identity, credentials/vault,
+migrations, payments, security, and publishable `packages/*` changes. Factory
+does not silently auto-merge, assign, or claim a provider action succeeded
+without a terminal record.
+
+## Configure Slack
+
+Set `WORKSPACE_OWNER_EMAIL` to an existing workspace member for the deployment-
+owned scheduler job. Connect Slack in Settings -> Messaging; Factory resolves
+the workspace credential through the vault resolver and only uses
+`SLACK_BOT_TOKEN` as the resolver's deployment fallback. Do not add a second
+env-only read.
+
+In Factory, set the Slack workspace, channel ID, channel name, repository, and
+polling switch. The default scheduler polls once per minute, evaluates a
+bounded page, and preserves errors for reconciliation.
+
+The generic Slack bot is wired to Factory. Mention `@agent-native` in a feedback
+thread to inspect the linked item, explain its decision, tune a rule, or say
+"do it now" to create an approval-gated run. The bot replies with an
+inspectable Factory link when a human decision is required.
+
+## Hosting
+
+Production expects a direct PostgreSQL `DATABASE_URL`,
+`WORKSPACE_OWNER_EMAIL`, and `FACTORY_PUBLIC_URL`. The Builder executor also
+needs `BUILDER_AI_SERVICES_URL` and `BUILDER_PROJECT_ID`; its private key and
+signed callback secret belong in workspace credentials and are resolved at
+runtime. The app remains observe-only until a human explicitly approves a
+Factory item.
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter factory dev
+pnpm --filter factory typecheck
+pnpm --filter factory test
+pnpm --filter factory build
+```

package/corpus/templates/factory/_gitignore

@@ -0,0 +1,42 @@
+# React Router generated types
+.react-router/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+node_modules
+build/
+dist
+dist-ssr
+.output/
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Data
+data/uploads/
+data/settings.json
+data/.sessions.json
+
+# Learnings (personal preferences and memory — use learnings.defaults.md for tracked defaults)
+learnings.md
+
+.vercel/
+.agent-native/

package/corpus/templates/factory/actions/add-factory-comment.ts

@@ -0,0 +1,55 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { getDb } from "../server/db/index.js";
+import { factoryComments } from "../server/db/schema.js";
+import { DEFAULT_FACTORY_ID } from "../server/factory-graph/store.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+import { stableId } from "../server/triage/ids.js";
+
+export default defineAction({
+  description:
+    "Add a review comment to a Factory canvas, node, or edge. Comments are durable collaboration context and do not change or execute the Factory.",
+  schema: z.object({
+    factoryId: z.string().trim().min(1).max(120).default(DEFAULT_FACTORY_ID),
+    graphVersion: z.coerce.number().int().positive(),
+    targetType: z.enum(["canvas", "node", "edge"]).default("canvas"),
+    targetId: z.string().trim().max(120).optional(),
+    body: z.string().trim().min(1).max(4_000),
+  }),
+  run: async (
+    { factoryId, graphVersion, targetType, targetId, body },
+    context,
+  ) => {
+    const { userEmail, orgId } = await requireWorkspaceMember(
+      workspaceMemberIdentityFromContext(context),
+    );
+    const id = stableId(
+      "factory-comment",
+      orgId,
+      factoryId,
+      String(graphVersion),
+      targetType,
+      targetId ?? "canvas",
+      body,
+      new Date().toISOString(),
+    );
+    await getDb()
+      .insert(factoryComments)
+      .values({
+        id,
+        factoryId,
+        graphVersion,
+        targetType,
+        targetId: targetId ?? null,
+        body,
+        createdAt: new Date().toISOString(),
+        ownerEmail: userEmail,
+        orgId,
+      });
+    return { ok: true, id, factoryId, graphVersion, targetType, targetId };
+  },
+});

package/corpus/templates/factory/actions/approve-factory-item.ts

@@ -0,0 +1,214 @@
+import { defineAction } from "@agent-native/core/action";
+import { and, asc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb } from "../server/db/index.js";
+import {
+  triageDecisions,
+  triageItems,
+  triageRuns,
+} from "../server/db/schema.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+import { startBuilderRun } from "../server/triage/builder-executor.js";
+import { stableId } from "../server/triage/ids.js";
+
+export default defineAction({
+  description:
+    "Explicitly approve one Factory item and start one deduplicated Builder coding run. The approver, decision, guard results, and callback state are recorded before provider work is considered successful.",
+  schema: z.object({
+    itemId: z.string().min(1),
+    decisionId: z.string().min(1).optional(),
+    confirm: z.literal(true),
+  }),
+  // Slack content and scheduled observations are untrusted. A provider run
+  // must remain paused until a human approves this exact agent tool call.
+  needsApproval: true,
+  http: { method: "POST" },
+  run: async ({ itemId, decisionId, confirm }, context) => {
+    if (!confirm) throw new Error("Explicit confirmation is required.");
+    const { userEmail, orgId } = await requireWorkspaceMember(
+      workspaceMemberIdentityFromContext(context),
+    );
+    const db = getDb();
+    const item = (
+      await db
+        .select()
+        .from(triageItems)
+        .where(and(eq(triageItems.id, itemId), eq(triageItems.orgId, orgId)))
+        .limit(1)
+    )[0];
+    if (!item) throw new Error("Factory item not found.");
+
+    const decisions = await db
+      .select()
+      .from(triageDecisions)
+      .where(
+        and(
+          eq(triageDecisions.orgId, orgId),
+          eq(triageDecisions.itemId, itemId),
+        ),
+      )
+      .orderBy(asc(triageDecisions.createdAt));
+    const decision = decisionId
+      ? decisions.find((entry) => entry.id === decisionId)
+      : decisions[decisions.length - 1];
+    if (!decision)
+      throw new Error("Evaluate the Factory item before approving it.");
+
+    const guardResults = parseGuardResults(decision.guardResultsJson);
+    const blocked = guardResults.filter((result) => result.passed === false);
+    if (blocked.length > 0) {
+      throw new Error(
+        `Factory approval blocked by hard guards: ${blocked.map((result) => result.reason).join(" ")}`,
+      );
+    }
+
+    const dedupeKey = stableId("builder", orgId, itemId, decision.id);
+    const runId = stableId("run", dedupeKey);
+    const existing = (
+      await db
+        .select()
+        .from(triageRuns)
+        .where(and(eq(triageRuns.id, runId), eq(triageRuns.orgId, orgId)))
+        .limit(1)
+    )[0];
+    if (
+      existing &&
+      ["submitted", "acknowledged", "running", "completed"].includes(
+        existing.status,
+      )
+    ) {
+      return { ok: true, deduplicated: true, run: existing };
+    }
+
+    const now = new Date().toISOString();
+    await db
+      .insert(triageRuns)
+      .values({
+        id: runId,
+        itemId,
+        source: item.source,
+        provider: "builder-http",
+        dedupeKey,
+        approvalEmail: userEmail,
+        status: "submitted",
+        progressLogJson: JSON.stringify([
+          {
+            at: now,
+            state: "submitted",
+            reason: "Explicit Factory approval recorded.",
+          },
+        ]),
+        dispatchAttempts: (existing?.dispatchAttempts ?? 0) + 1,
+        needsContinuation: 0,
+        startedAt: now,
+        heartbeatAt: now,
+        completedAt: null,
+        error: null,
+        ownerEmail: item.ownerEmail,
+        orgId,
+      })
+      .onConflictDoNothing();
+
+    const run = (
+      await db
+        .select()
+        .from(triageRuns)
+        .where(and(eq(triageRuns.id, runId), eq(triageRuns.orgId, orgId)))
+        .limit(1)
+    )[0];
+    if (!run) throw new Error("Factory run could not be recorded.");
+    if (run.status !== "submitted")
+      return { ok: true, deduplicated: true, run };
+
+    try {
+      const result = await startBuilderRun({
+        runId,
+        itemId,
+        ownerEmail: userEmail,
+        orgId,
+        repository: item.repository,
+        summary: item.summary,
+        sourceUrl: item.sourceUrl,
+      });
+      const progress = [
+        {
+          at: now,
+          state: "submitted",
+          reason: "Explicit Factory approval recorded.",
+        },
+        {
+          at: new Date().toISOString(),
+          state: "acknowledged",
+          reason:
+            "Builder accepted the fire-and-forget request; waiting for signed callback.",
+        },
+      ];
+      await db
+        .update(triageRuns)
+        .set({
+          status: "acknowledged",
+          providerTaskId: result.providerTaskId ?? null,
+          progressLogJson: JSON.stringify(progress),
+          heartbeatAt: new Date().toISOString(),
+        })
+        .where(and(eq(triageRuns.id, runId), eq(triageRuns.orgId, orgId)));
+      await db
+        .update(triageItems)
+        .set({ status: "classified", updatedAt: new Date().toISOString() })
+        .where(and(eq(triageItems.id, itemId), eq(triageItems.orgId, orgId)));
+      return {
+        ok: true,
+        deduplicated: false,
+        runId,
+        branchName: result.branchName,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      await db
+        .update(triageRuns)
+        .set({
+          status: "failed",
+          error: message,
+          completedAt: new Date().toISOString(),
+          heartbeatAt: new Date().toISOString(),
+        })
+        .where(and(eq(triageRuns.id, runId), eq(triageRuns.orgId, orgId)));
+      throw new Error(
+        `Factory approval was recorded, but Builder dispatch failed: ${message}`,
+      );
+    }
+  },
+});
+
+function parseGuardResults(
+  value: string,
+): Array<{ passed: boolean; reason: string }> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("Factory decision guard results are unreadable.");
+  }
+  if (!Array.isArray(parsed))
+    throw new Error("Factory decision guard results are unreadable.");
+  return parsed.map((entry) => {
+    if (
+      !entry ||
+      typeof entry !== "object" ||
+      typeof (entry as { passed?: unknown }).passed !== "boolean"
+    ) {
+      throw new Error("Factory decision guard results are unreadable.");
+    }
+    return {
+      passed: (entry as { passed: boolean }).passed,
+      reason: String(
+        (entry as { reason?: unknown }).reason ??
+          "Guard did not provide a reason.",
+      ),
+    };
+  });
+}