sonamu 0.10.7 → 0.10.9

package/src/skills/AGENTS.md

@@ -1,108 +0,0 @@
-# Guide for Coding Agents - modules/sonamu/src/skills
-
-Inherits rules from:
-
-- `../../../../AGENTS.md`
-- `../../AGENTS.md`
-
-## Directory role
-
-Source of truth for the Sonamu skills that `sonamu skills sync` installs into user projects.
-
-```
-skills/
-├── sonamu/                 root skill — routing table + cross-cutting conventions
-└── sonamu-<name>/          each directory is one agent skill
-    ├── SKILL.md            entry point (target ≤ 12KB, hard limit 20KB)
-    └── references/*.md     detail, loaded only when needed (hard limit 20KB)
-```
-
-Size limits are enforced by `scripts/check-skill-size.ts`, wired into root `pnpm check`.
-They are derived from measured Expo (max 19.1KB) and Vercel (max 17.3KB) skill sizes.
-
-## Skill boundary rule
-
-A document belongs in a skill only if it has a **discrete trigger moment** — a point where an
-agent can decide "now I need this". Content that applies to every turn (type-safety policy,
-lint gates, universal conventions) is horizontal and belongs in the root `sonamu` skill
-instead, because no specific skill will surface it at the right moment.
-
-Split criteria when adding or reorganizing:
-
-1. Documents read together in one task belong in one skill.
-2. Each skill's `description` must state its trigger moment, distinctly from every other skill.
-3. Prefer small duplication over cross-skill references. Skills load independently, so pointing
-   from one skill to another forces both into context.
-
-## Description format
-
-Every `description` is one line in three parts, matching what Expo and Vercel ship:
-
-```
-<What it does>. Use when <discrete trigger moments>. Covers <concrete symbols and commands>.
-```
-
-- **What** — third-person verb, no "This skill…". "Generates and applies Sonamu database
-  migrations."
-- **Use when** — the moments an agent can recognise. Name failures too, not just intentions:
-  "a migration fails or conflicts" catches cases "modifying a schema" misses. Never restate the
-  skill name — "Use when implementing internationalization" tells an agent nothing.
-- **Covers** — concrete identifiers an agent is likely to have in context: commands, decorators,
-  function names, error strings. This is matching surface, so prefer `executeSubsetQuery` and
-  `pg_trgm` over "query helpers".
-
-Keep it under ~400 characters. A well-formed trigger is necessary but not sufficient: Vercel
-measured a correctly written description that still went uninvoked in 56% of cases because its
-trigger was horizontal ("when writing or reviewing React code" applies to every turn). Write
-triggers that name a discrete moment.
-
-`pnpm skills:index` parses this shape — it takes the `Use when` sentence and drops `Covers`.
-
-## Skill index
-
-The root `sonamu` skill carries a generated routing table. It exists because each skill's
-`description` only fires at its own trigger moment — work that matches none of them gets no
-skill at all, and the root skill's broad description catches that case.
-
-Never hand-edit the region between `<!-- SKILL-INDEX:START -->` and `<!-- SKILL-INDEX:END -->`:
-
-```bash
-pnpm skills:index
-```
-
-`pnpm check` fails when the index is stale.
-
-Users who want the table always in context can run `sonamu skills index`, which writes it into
-their project's `AGENTS.md` inside `<!-- SONAMU:START -->` markers. That edits a file the user
-owns, so it is never part of `skills sync` — it only runs when invoked explicitly.
-
-## Contributing a troubleshooting resolution
-
-Only for maintainers of this repository. Skills shipped to user projects describe how to *use*
-Sonamu — never how to contribute to it, and never anything specific to one company or client
-project.
-
-Suggest capturing a resolution when all of these hold:
-
-1. The session went error → investigation → fix → success.
-2. The fix revealed internal framework behavior or an undocumented constraint.
-3. The same problem is likely to hit other projects.
-
-Skip typos, missing imports, project-specific business logic bugs, and one-off environment
-issues.
-
-Then, before writing anything:
-
-1. Find the skill whose trigger moment matches, and read it. Appending to an existing skill is
-   the normal outcome; a new skill is rare and needs a distinct trigger moment of its own.
-2. Check that the content is not already covered. Duplicates are the common failure here.
-3. Put horizontal rules in the root `sonamu` skill, not in a task skill.
-4. Get user confirmation before applying.
-
-Project-specific notes belong in that project's own skill directory
-(`.agents/skills/<name>/SKILL.md`), written by hand — never in this directory.
-
-## Cross-workspace gate
-
-- For changes in this scope, root `pnpm check` (oxlint + oxfmt + skill size + skill index) must
-  pass before handoff.

package/src/skills/sonamu/SKILL.md

@@ -1,75 +0,0 @@
----
-name: sonamu
-description: Routes Sonamu work to the right skill and carries the conventions that apply to every change. Use when starting work in a Sonamu project, or when no specific Sonamu skill obviously covers the problem. Covers the skill index, TypeScript type-safety rules, the tsc and pnpm check gate, and the packages/api command path.
----
-
-# Sonamu
-
-Sonamu is a TypeScript full-stack framework. Work is split across focused skills — find yours
-below and invoke it rather than working from memory.
-
-## Skill index
-
-<!-- SKILL-INDEX:START -->
-
-| Situation | Skill |
-| --- | --- |
-| implementing an agent class, defining its tools, or managing per-request agent state | `sonamu-ai-agents` |
-| adding or changing an API endpoint, choosing httpMethod/guards/clients options, or implementing a file upload | `sonamu-api` |
-| running auth generate, applying Guards to an endpoint, reading the session from Context, adding an auth plugin, or migrating User.id to a string primary key | `sonamu-auth` |
-| editing .env or sonamu.config.ts, adjusting auth, guards, storage, cache, or logging options, starting the Docker database, or resolving a port conflict | `sonamu-config` |
-| creating or editing an entity.json, adding a field or enum, wiring BelongsToOne/HasMany/ManyToMany/parentId, defining a subset, or resolving a schema validation or sync error | `sonamu-entity` |
-| running fixture gen/fetch/explore, writing cone.note metadata for LLM generation, syncing between the development, test, and fixture databases, or when a fixture fails on a foreign key or unique constraint | `sonamu-fixture` |
-| calling a generated Service, wiring a TanStack Query hook, building a form or list view, or when a scaffolded view fails to compile | `sonamu-frontend` |
-| registering labels for a new entity or enum, adding a language, or a UI string renders as a raw key | `sonamu-i18n` |
-| a schema change needs a migration, a migration fails or conflicts, FK ordering breaks an apply, or a primary key type must change | `sonamu-migration` |
-| a query or save produces the wrong result and the cause is unclear, or when a test needs to assert on internal state | `sonamu-naite` |
-| implementing a Model CRUD method, writing a SELECT/WHERE/JOIN query, batch-saving relation data, or when a query returns unexpected rows or an excessively deep type error | `sonamu-query` |
-| implementing a background job, scheduling recurring work, or building a multi-step process that must survive a restart | `sonamu-tasks` |
-| authoring a Model or API test, asserting on query behaviour, mocking a dependency, or when sonamu test fails to run | `sonamu-testing` |
-| generating embeddings, chunking documents, or combining vector similarity with full-text search | `sonamu-vector` |
-
-<!-- SKILL-INDEX:END -->
-
-Nothing matched? The problem is probably not Sonamu-specific — proceed normally.
-
----
-
-## Conventions that apply to every change
-
-These are not tied to one task, so no skill will surface them at the right moment. Copy them
-into your project's own `AGENTS.md` if you want them enforced on every turn.
-
-### TypeScript type safety
-
-- `as any` and `as unknown as T` are strictly prohibited.
-- Resolve type errors through correct type annotations, generic constraints, type narrowing, or
-  interface extension.
-- Do not use `as any` to work around "excessively deep" or similar TypeScript inference limits —
-  find the correct access pattern instead (e.g. use `getPuri("r")` directly rather than casting
-  the result).
-- Chaining methods after `as any` bypasses all TypeScript signature checks and leads directly to
-  runtime bugs.
-- Non-null assertion (`!`) is prohibited. Use optional chaining (`?.`) or type guard filters
-  instead.
-
-### Code quality gate
-
-After editing any `.ts` or `.tsx` file, run both before considering the task done:
-
-1. `npx tsc --noEmit --skipLibCheck` — type errors
-2. `pnpm check` — lint and format (oxlint + oxfmt)
-
-Do not skip lint/format even when tsc passes. oxlint catches `noNonNullAssertion`, import order,
-and other issues that tsc does not.
-
-### Command execution path
-
-All `pnpm` commands are run from the **`packages/api`** directory.
-
-```bash
-cd packages/api
-pnpm dev
-pnpm sonamu test
-pnpm sonamu migrate run
-```

package/src/skills/sonamu-ai-agents/SKILL.md

@@ -1,205 +0,0 @@
----
-name: sonamu-ai-agents
-description: Builds tool-using AI agents on Sonamu. Use when implementing an agent class, defining its tools, or managing per-request agent state. Covers BaseAgentClass, the @tools decorator, ToolLoopAgent, and AsyncLocalStorage state.
----
-
-# AI Agent Guide
-
-Sonamu provides a framework that wraps Vercel AI SDK's `ToolLoopAgent` to build class-based AI Agents.
-
-**Source code:** `modules/sonamu/src/ai/agents/`
-
----
-
-## Structure
-
-| File       | Role                                                                    |
-| ---------- | ----------------------------------------------------------------------- |
-| `agent.ts` | `BaseAgentClass`, `tools` decorator                                     |
-| `types.ts` | `AgentConfig`, `ToolDecoratorOptions`, `RegisteredToolDefinition`, etc. |
-
----
-
-## BaseAgentClass
-
-The base class for Agents. Extend it to create a custom Agent.
-
-```typescript
-import { BaseAgentClass, tools } from "sonamu/ai/agents";
-import { z } from "zod/v4";
-
-class MyAgentClass extends BaseAgentClass<{ count: number }> {
-  constructor() {
-    super("MyAgent"); // agentName (used as logger category)
-  }
-
-  @tools({
-    description: "Adds two numbers",
-    schema: {
-      input: z.object({ a: z.number(), b: z.number() }),
-      output: z.object({ result: z.number() }),
-    },
-  })
-  async add(input: { a: number; b: number }) {
-    return { result: input.a + input.b };
-  }
-}
-
-export const MyAgent = new MyAgentClass();
-```
-
-### Key Features
-
-| Feature       | Description                                 |
-| ------------- | ------------------------------------------- |
-| `this.logger` | LogTape logger (agent category)             |
-| `this.store`  | AsyncLocalStorage-based state access        |
-| `this.tools`  | Registered toolset (ToolSet)                |
-| `this.use()`  | Run the Agent (ALS context + ToolLoopAgent) |
-
----
-
-## @tools Decorator
-
-Registers a method as an AI tool. Define input/output using Zod v4 schema.
-
-```typescript
-@tools({
-  name?: string,           // Tool name (default: "className.methodName" format)
-  description?: string,    // Description shown to the LLM
-  schema: {
-    input: z.ZodType,      // Input schema (required)
-    output?: z.ZodType,    // Output schema (optional)
-  },
-  needsApproval?: boolean | function,  // Whether user approval is required
-  toModelOutput?: function,            // Transform output returned to the model
-  providerOptions?: ProviderOptions,   // Provider-specific options
-})
-```
-
-### Automatic Name Generation Rule
-
-If `name` is omitted, it is auto-generated as `{ModelName(camelCase)}.{methodName(camelCase)}`.
-
-```typescript
-class SearchAgentClass extends BaseAgentClass<...> {
-  @tools({ ... })
-  async findDocuments(input: ...) { ... }
-  // → Tool name: "searchAgent.findDocuments"
-}
-```
-
-The suffixes `Class`, `Model`, and `Frame` are automatically stripped from the class name.
-
----
-
-## Running an Agent (use)
-
-Run the Agent with the `use()` method. ToolLoopAgent operates within the AsyncLocalStorage context.
-
-```typescript
-import { anthropic } from "@ai-sdk/anthropic";
-
-const result = await MyAgent.use(
-  // AgentConfig
-  {
-    model: anthropic("claude-sonnet-4-6"),
-    instructions: "You are a math assistant.",
-    toolChoice: "auto", // "auto" | "none" | "required"
-    maxOutputTokens: 1000,
-    temperature: 0.7,
-  },
-  // Initial state (stored in AsyncLocalStorage)
-  { count: 0 },
-  // Callback (receives Agent instance)
-  async (agent) => {
-    // agent is a ToolLoopAgent instance
-    // Use Vercel AI SDK's agent API
-    return agent;
-  },
-);
-```
-
-### AgentConfig Options
-
-| Option                                 | Type                             | Description                          |
-| -------------------------------------- | -------------------------------- | ------------------------------------ |
-| `model`                                | `LanguageModel`                  | AI SDK model (required)              |
-| `instructions`                         | `string`                         | System prompt                        |
-| `toolChoice`                           | `"auto" \| "none" \| "required"` | Tool selection strategy              |
-| `stopWhen`                             | `StopCondition`                  | Stop condition                       |
-| `activeTools`                          | `string[]`                       | List of tool names to activate       |
-| `maxOutputTokens`                      | `number`                         | Maximum output tokens                |
-| `temperature`                          | `number`                         | Temperature                          |
-| `topP` / `topK`                        | `number`                         | Sampling parameters                  |
-| `presencePenalty` / `frequencyPenalty` | `number`                         | Penalties                            |
-| `seed`                                 | `number`                         | Seed for reproducibility             |
-| `stopSequences`                        | `string[]`                       | Generation stop sequences            |
-| `providerOptions`                      | `ProviderOptions`                | Additional provider-specific options |
-| `headers`                              | `Record<string, string>`         | Custom HTTP headers                  |
-
----
-
-## State Management (AsyncLocalStorage)
-
-`BaseAgentClass` defines the state type with the generic `TStore`. When you pass the initial state to `use()`, it can be accessed via `this.store` during tool execution.
-
-```typescript
-class StatefulAgentClass extends BaseAgentClass<{ processedItems: string[] }> {
-  @tools({ ... })
-  async processItem(input: { item: string }) {
-    // Access state
-    this.store?.processedItems.push(input.item);
-    return { ok: true };
-  }
-}
-```
-
-**Note:** `this.store` is `undefined` outside of a `use()` context.
-
----
-
-## Tool Isolation
-
-Tools for each Agent class are isolated per class. The `toolSet` getter filters by `def.from === this.constructor.name`.
-
-```typescript
-class AgentA extends BaseAgentClass<void> {
-  @tools({ ... }) async toolX() { ... }
-}
-class AgentB extends BaseAgentClass<void> {
-  @tools({ ... }) async toolY() { ... }
-}
-
-// AgentA.tools → { contains only toolX }
-// AgentB.tools → { contains only toolY }
-```
-
----
-
-## Logging
-
-`this.logger` uses LogTape. The category is generated with `convertDomainToCategory(agentName, "agent")`.
-
-Debug logs are automatically recorded on tool execution:
-
-```
-tools: {model}.{method} with args: {args}
-```
-
----
-
-## Related Packages
-
-- `ai`: Vercel AI SDK (`ToolLoopAgent`, `Agent`, `ToolSet`)
-- `@ai-sdk/provider-utils`: `tool()`, `Tool`, `ToolExecutionOptions`
-- `zod/v4`: Schema definitions
-- `@logtape/logtape`: Logging
-
----
-
-## References
-
-- **Source code**: `modules/sonamu/src/ai/agents/`
-- **Vercel AI SDK**: https://sdk.vercel.ai/docs
-- **Vector search**: `sonamu-vector`