@agent-native/core 0.14.8 → 0.15.1

package/dist/templates/workspace-core/.agents/skills/automations/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: automations
+description: >-
+  Event-triggered and schedule-triggered automations with natural-language
+  conditions. Use when creating automations, wiring events, or understanding
+  how triggers fire.
+---
+
+# Automations
+
+## Rule
+
+Automations are agent-executed tasks that fire in response to events or on a cron schedule. Each automation is a markdown resource under `jobs/` with YAML frontmatter describing when and how it fires, and a body containing natural-language instructions the agent follows. Automations extend the recurring-jobs system with event triggers, natural-language condition evaluation, and outbound HTTP via the `web-request` tool.
+
+## The Two Trigger Types
+
+| Type       | Fires when                                      | Key field           |
+| ---------- | ----------------------------------------------- | ------------------- |
+| `schedule` | Cron expression matches (same as recurring jobs) | `schedule` (cron)   |
+| `event`    | A matching event is emitted on the event bus     | `event` (event name) |
+
+Event triggers can optionally include a `condition` -- a natural-language string evaluated by Haiku against the event payload before dispatch. If the condition does not match, the automation is skipped.
+
+## How It Works
+
+1. User asks the agent to create an automation (or uses the settings UI).
+2. Agent calls `manage-automations` with `action=list-events` to discover available events.
+3. Agent calls `manage-automations` with `action=define` to write a `jobs/<name>.md` resource.
+4. The trigger dispatcher subscribes to the event on the bus.
+5. When the event fires, the dispatcher loads all matching triggers, evaluates conditions via Haiku, and dispatches matching ones.
+6. In `agentic` mode, the dispatcher runs a full `runAgentLoop` with the automation body as the prompt and the event payload as context.
+7. Status (`lastRun`, `lastStatus`, `lastError`) is written back to the resource frontmatter.
+
+## Markdown Format
+
+```yaml
+---
+schedule: "0 9 * * 1-5"
+enabled: true
+triggerType: event
+event: calendar.booking.created
+condition: "attendee email ends with @example.com"
+mode: agentic
+domain: calendar
+createdBy: owner@example.com
+runAs: creator
+---
+
+Send a Slack message to #sales with the booking details.
+Use the web-request tool with ${keys.SLACK_WEBHOOK}.
+```
+
+### Frontmatter Fields
+
+| Field         | Type                           | Purpose                                                |
+| ------------- | ------------------------------ | ------------------------------------------------------ |
+| `schedule`    | `string`                       | Cron expression (required for schedule triggers)       |
+| `enabled`     | `boolean`                      | Whether the automation is active                       |
+| `triggerType` | `"schedule" \| "event"`        | How the automation fires                               |
+| `event`       | `string?`                      | Event name to subscribe to (event triggers)            |
+| `condition`   | `string?`                      | Natural-language condition evaluated before dispatch   |
+| `mode`        | `"agentic" \| "deterministic"` | Full agent loop vs. fixed action set                   |
+| `model`       | `string?`                      | Override the model for this trigger's agent loop       |
+| `domain`      | `string?`                      | Grouping tag (mail, calendar, clips, etc.)             |
+| `createdBy`   | `string?`                      | Owner email                                            |
+| `orgId`       | `string?`                      | Org scope                                              |
+| `runAs`       | `"creator" \| "shared"`        | Whose API key and permissions to use                   |
+| `lastRun`     | `string?`                      | ISO timestamp of last execution                        |
+| `lastStatus`  | `string?`                      | `success`, `error`, `running`, or `skipped`            |
+| `lastError`   | `string?`                      | Error message from last failed run                     |
+
+## Agent Tools
+
+All automation operations are accessed through a single `manage-automations` tool with an `action` parameter:
+
+| Action        | Purpose                                                              |
+| ------------- | -------------------------------------------------------------------- |
+| `list-events` | Discover all registered events with descriptions and payload schemas |
+| `list`        | List all automations with status, filter by domain or enabled        |
+| `define`      | Create a new automation (name, trigger type, event, condition, body)  |
+| `update`      | Update an existing automation (enabled, condition, body)             |
+| `delete`      | Delete an automation (always confirm with user first)                |
+| `fire-test`   | Emit a `test.event.fired` event to validate automations              |
+
+Additional tool: `web-request` — outbound HTTP with `${keys.NAME}` substitution.
+
+## The Event Bus
+
+Integrations register events at module load time. The bus validates payloads against Standard Schema definitions and dispatches to subscribers.
+
+```ts
+import { registerEvent, emit } from "@agent-native/core/event-bus";
+import { z } from "zod";
+
+// Register an event type (typically in a server plugin)
+registerEvent({
+  name: "calendar.booking.created",
+  description: "A new calendar booking was created",
+  payloadSchema: z.object({
+    bookingId: z.string(),
+    attendeeEmail: z.string(),
+    startTime: z.string(),
+  }),
+  example: { bookingId: "abc", attendeeEmail: "jane@co.com", startTime: "2025-01-15T10:00:00Z" },
+});
+
+// Emit the event (from an action, webhook handler, etc.)
+emit("calendar.booking.created", {
+  bookingId: "abc",
+  attendeeEmail: "jane@co.com",
+  startTime: "2025-01-15T10:00:00Z",
+}, { owner: "owner@example.com" });
+```
+
+### Built-in Events
+
+| Event                     | Source              |
+| ------------------------- | ------------------- |
+| `test.event.fired`        | Manual / manage-automations action=fire-test |
+| `agent.turn.completed`    | Agent chat          |
+| `calendar.*`              | Calendar integration |
+| `clip.*`                  | Clips integration   |
+| `mail.*`                  | Mail integration    |
+
+### Event Bus API
+
+| Function         | Purpose                                     |
+| ---------------- | ------------------------------------------- |
+| `registerEvent`  | Declare an event type with schema           |
+| `emit`           | Fire an event (validates payload)           |
+| `subscribe`      | Listen for an event (returns subscription ID) |
+| `unsubscribe`    | Remove a subscription by ID                 |
+| `listEvents`     | List all registered event definitions       |
+
+## Condition Evaluator
+
+When an automation has a `condition`, the dispatcher calls Haiku (claude-haiku-4-5) to classify whether the event payload satisfies the condition. This is a yes/no classification, not a generation task.
+
+- Empty or missing condition = unconditional (always fires).
+- Results are memoized (SHA-256 of condition + payload) with a 5-minute TTL and 500-entry LRU cache.
+- Payload is truncated to 4000 characters before sending to Haiku.
+- On API failure, the condition evaluates to `false` (safe default -- skips the automation).
+
+## The `web-request` Tool and Keys
+
+Automations use the `web-request` tool for outbound HTTP. It supports `${keys.NAME}` placeholders in the URL, headers, and body. These are resolved server-side after the agent emits the tool call -- the raw secret value never enters the agent's context.
+
+- Keys are ad-hoc secrets created by the user via the settings UI or the `/_agent-native/secrets/adhoc` API.
+- Each key can have a URL allowlist that restricts which origins the key can be sent to.
+- `resolveKeyReferences()` resolves placeholders, falling back from user scope to workspace scope.
+- `validateUrlAllowlist()` checks the resolved URL against per-key allowlists (origin-level matching).
+
+## UI
+
+Automations appear in the settings panel under an "Automations" section. Users can view, enable/disable, and delete automations from there. Creation typically happens through the agent chat.
+
+## Example
+
+User: "When someone books a meeting with a @example.com email, message me in Slack."
+
+Agent flow:
+
+1. Calls `manage-automations` with `action=list-events` to find `calendar.booking.created`.
+2. Confirms the plan with the user.
+3. Calls `manage-automations` with `action=define`:
+   - `name`: `slack-on-builder-booking`
+   - `trigger_type`: `event`
+   - `event`: `calendar.booking.created`
+   - `condition`: `attendee email ends with @example.com`
+   - `mode`: `agentic`
+   - `domain`: `calendar`
+   - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
+
+## Key Files
+
+| File                                           | Purpose                                          |
+| ---------------------------------------------- | ------------------------------------------------ |
+| `packages/core/src/triggers/types.ts`          | `TriggerFrontmatter` interface                   |
+| `packages/core/src/triggers/actions.ts`        | Agent tools (define, list, update, delete, test)  |
+| `packages/core/src/triggers/dispatcher.ts`     | Event subscription and agentic dispatch          |
+| `packages/core/src/triggers/condition-evaluator.ts` | Haiku condition classification with caching |
+| `packages/core/src/event-bus/`                 | Event bus (register, emit, subscribe)            |
+| `packages/core/src/tools/fetch-tool.ts`        | `web-request` tool with key substitution         |
+| `packages/core/src/secrets/substitution.ts`    | `resolveKeyReferences()` and `validateUrlAllowlist()` |
+
+## Related Skills
+
+- `recurring-jobs` -- schedule-triggered automations reuse the same scheduler
+- `secrets` -- ad-hoc keys and `${keys.NAME}` substitution
+- `actions` -- automations can call any registered action via the agent loop
+- `delegate-to-agent` -- agentic mode runs a full `runAgentLoop`

package/dist/templates/workspace-core/.agents/skills/capture-learnings/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: capture-learnings
+description: >-
+  Capture and apply accumulated knowledge via structured memory. Use when the
+  user gives feedback, shares preferences, corrects a mistake, or when you
+  discover something worth remembering for future conversations.
+user-invocable: false
+---
+
+# Capture Learnings
+
+This is background knowledge, not a slash command. **Your memory index is loaded at the start of every conversation.** Use `save-memory` proactively when you learn something worth remembering.
+
+## How to Read & Write Memories
+
+Memories are stored as **resources** in the SQL database (personal scope), not as files on disk.
+
+- **Save a memory:** `save-memory --name <name> --type <type> --description "..." --content "..."`
+- **Read a memory:** `resource-read --path memory/<name>.md`
+- **Delete a memory:** `delete-memory --name <name>`
+- **List all memories:** `resource-list --prefix memory/`
+
+## Memory Types
+
+| Type | Use for |
+|------|---------|
+| `user` | Preferences, role, personal context, contacts |
+| `feedback` | Corrections, confirmed approaches, things to avoid or repeat |
+| `project` | Ongoing work context, decisions, deadlines, status |
+| `reference` | Pointers to external systems, URLs, API details |
+
+## When to Capture
+
+### User Preferences & Memory (`user`)
+- **Tone and style** — "I prefer casual tone", "don't use emojis", "keep replies short"
+- **Personal context** — contacts, relationships, habits ("my wife's email is...", "I'm in PST timezone")
+- **Workflow preferences** — "always CC my assistant", "I like to review before sending"
+- **Role and expertise** — "I'm a data scientist", "new to React"
+
+### Feedback & Corrections (`feedback`)
+- **Corrections** — user says "no, do it this way" → capture the right way
+- **Confirmed approaches** — user validates a non-obvious choice ("yes, that's perfect")
+- **Repeated friction** — you hit the same issue twice; save it
+
+### Project Context (`project`)
+- **Ongoing work** — who is doing what, why, by when
+- **Decisions** — why something is done a certain way
+- **Status** — current state of initiatives
+
+### References (`reference`)
+- **External systems** — "bugs are tracked in Linear project INGEST"
+- **URLs** — dashboards, documentation, tools
+- **API quirks** — undocumented behavior, version-specific gotchas
+
+### Don't Capture
+- Things obvious from reading the code
+- Standard language/framework behavior
+- Temporary debugging notes
+- Anything already in AGENTS.md or skills
+- Ephemeral task details (use tasks/plans instead)
+
+## Key Rules
+
+1. **Save proactively — don't ask permission.** When you learn something, save it immediately.
+2. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
+3. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
+4. **Keep descriptions concise** — the index is loaded every conversation
+5. **Memories are SQL-backed** — safe for personal info, persist across sessions, not in git
+
+## Graduation
+
+When a memory is referenced repeatedly, it may belong in AGENTS.md or a skill:
+- Saving a memory is lightweight (auto-apply, personal scope)
+- Updating AGENTS.md or a skill is heavier (affects all users/agents)

package/dist/templates/workspace-core/.agents/skills/client-side-routing/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: client-side-routing
+description: >-
+  How to add routes without remounting the app shell. Use when adding a new
+  route, fixing agent sidebar reloads on navigation, or choosing between
+  `root.tsx` layout and pathless `_app.tsx` layout patterns.
+---
+
+# Client-Side Routing
+
+## Rule
+
+All templates are single-page apps using React Router. **Navigation must not remount the app shell.** The agent sidebar, document tree, and any other persistent chrome must survive route changes.
+
+## Why
+
+If the shell unmounts on every navigation, the agent chat reconnects/reloads, destroying in-progress work and hammering the backend.
+
+## Hard Rule
+
+**The app shell (AgentSidebar + any top-level navigation) must be mounted ONCE, above the `<Outlet />`.** Never wrap each page in its own `<AppLayout>` / `<Layout>`. React sees a different component at the outlet position on each nav and unmounts the entire subtree.
+
+## Two Correct Patterns
+
+### 1. All routes need the shell
+
+Mount `<AppLayout>` in `root.tsx` around `<Outlet />`:
+
+```tsx
+// app/root.tsx
+<AppLayout>
+  <Outlet />
+</AppLayout>
+```
+
+### 2. Mix of protected and public routes
+
+Use a React Router **pathless layout route**:
+
+```
+app/routes/
+  _app.tsx                  # renders <AppLayout><Outlet /></AppLayout>
+  _app._index.tsx           # / → under AppLayout
+  _app.settings.tsx         # /settings → under AppLayout
+  _app.team.tsx             # /team → under AppLayout
+  book.$slug.tsx            # /book/:slug → no layout (public)
+  f.$.tsx                   # /f/* → no layout (public form filler)
+```
+
+The `_` prefix on `_app.tsx` makes it a **pathless** parent — it contributes the layout but no URL segment. Route files prefixed with `_app.` nest under it and share the layout instance across navigations.
+
+## Anti-Pattern
+
+```tsx
+// ❌ BAD — each route wraps its own Layout, causing full remount on every nav
+export default function Settings() {
+  return (
+    <AppLayout>
+      <SettingsContent />
+    </AppLayout>
+  );
+}
+```
+
+If a page needs per-route data (e.g. sidebar highlighting the active document), derive it inside the layout from `useParams()` / `useLocation()` — don't pass it as a prop through every route file.
+
+## Adding a New Route
+
+- **Pattern #1** (AppLayout in `root.tsx`): just render page content — nothing else.
+- **Pattern #2** (pathless `_app.tsx`): name the file `_app.<segment>.tsx` for authed routes, or bare `<segment>.tsx` for public routes.
+
+## Related Skills
+
+- `adding-a-feature` — The four-area checklist referencing route layout patterns
+- `context-awareness` — Navigation state written on every route change

package/dist/templates/workspace-core/.agents/skills/context-awareness/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: context-awareness
+description: >-
+  How the agent knows what the user is looking at. Use when exposing UI state to
+  the agent, implementing view-screen or navigate scripts, wiring navigation
+  state, or debugging agent context issues.
+---
+
+# Context Awareness
+
+## Rule
+
+The agent must always know what the user is currently viewing. The UI writes navigation state on every route change. The agent reads it before acting.
+
+## Why
+
+Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.
+
+## The Three Patterns
+
+### 1. Navigation State (`navigation` key)
+
+The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on and what item is selected.
+
+**UI side** — the `use-navigation-state.ts` hook:
+
+```ts
+// app/hooks/use-navigation-state.ts
+import { useEffect, useCallback } from "react";
+import { useLocation } from "react-router";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+export function useNavigationState() {
+  const location = useLocation();
+
+  // Sync route to app-state on every navigation
+  useEffect(() => {
+    const state = deriveNavigationState(location.pathname);
+    fetch("/_agent-native/application-state/navigation", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(state),
+    }).catch(() => {});
+  }, [location.pathname]);
+
+  // ... also listen for navigate commands (pattern 3)
+}
+```
+
+**Agent side** — read before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// e.g. { view: "thread", threadId: "abc123", subject: "Re: Q3 Planning" }
+```
+
+**What to include in navigation state:**
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
+- Filter state — active search, label, or category filters
+- Any selection — focused item, selected text range, active tab
+
+### 2. The `view-screen` Script
+
+Every template should have a `view-screen` script. It reads navigation state, fetches the relevant data from the API, and returns a snapshot of what the user sees. This is the agent's eyes.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const screen: Record<string, unknown> = { navigation };
+
+  // Fetch data based on what the user is viewing
+  if (navigation?.view === "inbox") {
+    const emails = await fetchEmailList(navigation.label);
+    screen.emailList = emails;
+  }
+  if (navigation?.threadId) {
+    const thread = await fetchThread(navigation.threadId);
+    screen.thread = thread;
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+**Navigation state is auto-injected into every user message as a `<current-screen>` block**, so the agent always has basic context without calling any tool. The `view-screen` action is still useful when you need a richer snapshot (e.g., fetching the full email thread or form data for the current view).
+
+### 3. The `navigate` Script
+
+The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+
+**Agent side:**
+
+```ts
+import { writeAppState } from "@agent-native/core/application-state";
+
+// Navigate the user to a specific thread
+await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
+```
+
+**UI side** — the hook polls for the command:
+
+```ts
+const { data: navCommand } = useQuery({
+  queryKey: ["navigate-command"],
+  queryFn: async () => {
+    const res = await fetch("/_agent-native/application-state/navigate");
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (data) {
+      // Delete the one-shot command after reading
+      fetch("/_agent-native/application-state/navigate", { method: "DELETE" });
+      return data;
+    }
+    return null;
+  },
+  staleTime: 2_000,
+});
+
+useEffect(() => {
+  if (navCommand) {
+    router.navigate(buildPath(navCommand));
+  }
+}, [navCommand]);
+```
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  queryKeys: ["app-state", "settings"],
+  ignoreSource: TAB_ID,  // ignore events from this tab's own writes
+});
+```
+
+The UI sends its tab ID via `X-Request-Source` header on PUT/DELETE requests. The server stores this as the event's `requestSource`. When polling, the UI filters out events matching its own `ignoreSource` value. This prevents the UI from refetching data it just wrote.
+
+## Gold-Standard Example: Mail Template
+
+The mail template demonstrates all three patterns working together:
+
+**Navigation state shape:**
+```json
+{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "search": "budget", "label": "important" }
+```
+
+**view-screen output:**
+- Reads navigation state
+- Fetches email list matching current view/search/label filters
+- Fetches thread messages if a thread is open
+- Returns everything as a single JSON snapshot
+
+**navigate command:**
+- `{ "view": "starred" }` — switch to starred view
+- `{ "view": "inbox", "threadId": "thread-123" }` — open a specific thread
+
+## Do
+
+- Use the auto-injected `<current-screen>` block for basic context — call `view-screen` only when you need richer data
+- Include all relevant selection state in the `navigation` key (view, item IDs, filters)
+- Update `view-screen` when adding new features — it should return data for every view
+- Use the one-shot `navigate` command pattern for agent-initiated navigation
+- Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
+
+## Don't
+
+- Don't assume the user is on a specific page — always check navigation state
+- Don't hardcode navigation paths in scripts — read the current state and branch
+- Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
+- Don't ignore the `<current-screen>` block — it tells you where the user is
+- Don't store fetched data in navigation state — it holds IDs and filters only. The `view-screen` script fetches the actual data.
+
+## Related Skills
+
+- **adding-a-feature** — Context awareness is area 4 of the four-area checklist
+- **real-time-sync** — How polling and `useDbSync` deliver app-state changes to the UI
+- **scripts** — How to create the `view-screen` and `navigate` scripts
+- **storing-data** — Application-state is one of the core SQL stores