sonamu 0.10.7 → 0.10.8

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`

package/src/skills/sonamu-api/SKILL.md

@@ -1,480 +0,0 @@
----
-name: sonamu-api
-description: Exposes Model methods as HTTP endpoints with the @api decorator. Use when adding or changing an API endpoint, choosing httpMethod/guards/clients options, or implementing a file upload. Covers @api, @upload, response subset selection, and the generated service client.
----
-
-# @api Decorator
-
-## Basic Usage
-
-```typescript
-@api({ httpMethod: "GET" })
-async findById(id: number): Promise<User> { }
-// → GET /user/findById?id=1
-```
-
-## Options
-
-| Option         | Description                                             | Default             |
-| -------------- | ------------------------------------------------------- | ------------------- |
-| `httpMethod`   | GET, POST, PUT, DELETE, PATCH                           | GET                 |
-| `clients`      | Client types to generate                                | `["axios"]`         |
-| `resourceName` | queryKey for TanStack Query                             | -                   |
-| `guards`       | Authentication/authorization guards                     | -                   |
-| `path`         | Custom path                                             | `/{model}/{method}` |
-| `description`  | API description (for documentation)                     | -                   |
-| `timeout`      | Request timeout (ms)                                    | -                   |
-| `contentType`  | Response Content-Type                                   | `application/json`  |
-| `cacheControl` | Cache-Control header setting                            | -                   |
-| `compress`     | Response compression setting (can disable with `false`) | -                   |
-
-## clients Options
-
-| Client                        | Purpose                  |
-| ----------------------------- | ------------------------ |
-| `axios`                       | General API calls        |
-| `axios-multipart`             | File upload (axios)      |
-| `tanstack-query`              | Query hook for reads     |
-| `tanstack-mutation`           | Mutation hook for writes |
-| `tanstack-mutation-multipart` | File upload Mutation     |
-| `window-fetch`                | Browser fetch API        |
-
-## Pattern Examples
-
-### Read API
-
-```typescript
-@api({
-  httpMethod: "GET",
-  clients: ["axios", "tanstack-query"],
-  resourceName: "Users",
-})
-async findMany(params: UserListParams): Promise<ListResult<User>> { }
-```
-
-### Write API
-
-```typescript
-@api({
-  httpMethod: "POST",
-  clients: ["axios", "tanstack-mutation"],
-})
-async save(params: UserSaveParams[]): Promise<number[]> { }
-```
-
-### API Requiring Authorization
-
-```typescript
-@api({ httpMethod: "POST", guards: ["admin"] })
-async del(ids: number[]): Promise<number> { }
-```
-
-## Context Access
-
-```typescript
-import { Sonamu } from "sonamu";
-
-@api({ httpMethod: "GET", guards: ["user"] })
-async me(): Promise<User | null> {
-  const { user } = Sonamu.getContext();
-  return user ? this.findById("A", user.id) : null;
-}
-```
-
-| Context Property | Description                                                         |
-| ---------------- | ------------------------------------------------------------------- |
-| `user`           | Authenticated user (better-auth User, null if unauthenticated)      |
-| `session`        | Current session info (better-auth Session, null if unauthenticated) |
-| `request`        | FastifyRequest                                                      |
-| `reply`          | FastifyReply                                                        |
-| `headers`        | HTTP request headers                                                |
-| `bufferedFiles`  | Buffer mode uploaded files                                          |
-| `uploadedFiles`  | Stream mode uploaded files                                          |
-| `locale`         | Request locale                                                      |
-
-## File Upload (@upload)
-
-> **CRITICAL: `@upload` is used standalone without `@api`.**
-> Adding `@upload` **automatically generates** a POST endpoint and `axios-multipart`/`tanstack-mutation-multipart` clients.
-> Adding `@api` alongside it causes a **build error** due to `checkSingleDecorator` conflict.
-
-```typescript
-// CORRECT
-@upload({ limits: { files: 10 }, guards: ["user"] })
-async upload(...): Promise<number[]> { }
-
-// WRONG — causes build error
-@api({ httpMethod: "POST", clients: ["axios-multipart"] })
-@upload({ limits: { files: 10 } })
-async upload(...): Promise<number[]> { }
-```
-
-**`@upload` supported options** (`httpMethod`, `clients` are not supported — set automatically)
-
-| Option         | Description                                         |
-| -------------- | --------------------------------------------------- |
-| `guards`       | Authentication/authorization guards                 |
-| `limits`       | File count/size limits (`{ files: N }`)             |
-| `consume`      | `"buffer"` (default) or `"stream"`                  |
-| `description`  | API documentation description                       |
-| `destination`  | Stream mode only: storage driver key                |
-| `keyGenerator` | Stream mode only: function to generate storage path |
-
-### Parameter Rule: Must Wrap in a Single Object
-
-> **CRITICAL: If an `@upload` method has 2 or more parameters, they must be wrapped into a single object.**
->
-> Using multiple primitive parameters causes a codegen bug in `services.template.ts` that generates `useUploadMutation` incorrectly.
-
-```typescript
-// WRONG — codegen breaks (missing mutationFn argument)
-async upload(entity_type: string, entity_id: number, file_type: string)
-
-// CORRECT — wrap in a single object
-async upload(params: { entity_type: string; entity_id: number; file_type: string })
-```
-
-Call site pattern:
-
-```typescript
-uploadMutation.mutate({
-  params: { entity_type, entity_id, file_type },
-  files,
-});
-```
-
-> Root cause: a `split(":")` bug in `services.template.ts` makes `useUploadMutation` drop
-> every primitive parameter after the first, so multiple primitives must be wrapped in one object.
-
-### Buffer Mode (Default)
-
-```typescript
-@upload({ limits: { files: 10 } })
-async uploadFiles(): Promise<{ files: SonamuFile[] }> {
-  const { bufferedFiles } = Sonamu.getContext();
-  // Access file data via bufferedFiles[].buffer
-}
-```
-
-### Stream Mode (Large Files)
-
-```typescript
-@upload({
-  consume: "stream",
-  destination: "s3",  // or "fs"
-  keyGenerator: (file) => `uploads/${Date.now()}-${file.filename}`,
-  limits: { files: 5 },
-})
-async uploadLargeFiles(): Promise<{ urls: string[] }> {
-  const { uploadedFiles } = Sonamu.getContext();
-  // Access stored path via uploadedFiles[].key
-}
-```
-
----
-
-## Real-world Business Logic Patterns
-
-### Transaction with History Logging
-
-Pattern for atomically handling main data and history together when changing state:
-
-```typescript
-// consultation.model.ts
-
-@api({ httpMethod: "POST", guards: ["user"] })
-async changeStatus(
-  id: number,
-  status: ConsultationStatus,
-  memo?: string
-): Promise<Consultation> {
-  const wdb = this.getPuri("w");
-
-  return wdb.transaction(async (trx) => {
-    // 1. Update consultation
-    await trx.ubRegister("consultations", {
-      id,
-      status,
-      updated_at: new Date()
-    });
-    await trx.ubUpsert("consultations");
-
-    // 2. Record status change history
-    await trx.ubRegister("consultation_histories", {
-      consultation_id: id,
-      status,
-      memo,
-      created_at: new Date(),
-    });
-    await trx.ubUpsert("consultation_histories");
-
-    // 3. Return result
-    return this.findById("A", id);
-  });
-}
-```
-
-**Key points:**
-
-- Atomicity guaranteed by transaction
-- ubRegister + ubUpsert pattern
-- Return latest data after change
-
-### Validation Logic and Business Rules
-
-Pattern for complex validation such as duplicate checks and capacity checks before registration:
-
-```typescript
-@api({ httpMethod: "POST", guards: ["user"] })
-async enroll(
-  courseId: number,
-  userId: number
-): Promise<Enrollment> {
-  // 1. Prevent duplicate registration
-  const existing = await this.findOne("A", {
-    course_id: courseId,
-    user_id: userId,
-  });
-
-  if (existing) {
-    throw new Error("Already enrolled in this course");
-  }
-
-  // 2. Check capacity
-  const course = await CourseModel.findById("A", courseId);
-  const { total } = await this.findMany({ course_id: courseId });
-
-  if (total >= course.max_students) {
-    throw new Error("Course is at capacity");
-  }
-
-  // 3. Enroll
-  const [id] = await this.save([{ course_id: courseId, user_id: userId }]);
-  return this.findById("A", id);
-}
-```
-
-**Key points:**
-
-- Step-by-step validation (duplicate → capacity)
-- Clear error messages
-- Save after validation passes
-
-### Using Authorization Guards
-
-Access control based on user role:
-
-```typescript
-// Regular user only
-@api({ httpMethod: "POST", guards: ["user"] })
-async save(spa: PostSaveParams[]): Promise<number[]> { }
-
-// Admin only
-@api({ httpMethod: "POST", guards: ["admin"] })
-async del(ids: number[]): Promise<number> { }
-
-// Using currently logged-in user info
-@api({ httpMethod: "GET", guards: ["user"] })
-async myConsultations(): Promise<ListResult<Consultation>> {
-  const { user } = Sonamu.getContext();
-  return this.findMany({ user_id: user!.id });
-}
-```
-
-### Writing API Tests
-
-Validating custom APIs in Business Logic tests:
-
-```typescript
-// consultation.test.ts
-describe("E. Business Logic", () => {
-  test("Status change API", async () => {
-    const { consultationId } = await createTestConsultationWithDeps();
-
-    // Call custom API
-    const updated = await ConsultationModel.changeStatus(
-      consultationId,
-      "completed",
-      "Consultation complete",
-    );
-
-    expect(updated.status).toBe("completed");
-
-    // Verify history was recorded
-    const histories = await ConsultationHistoryModel.findMany({
-      consultation_id: consultationId,
-    });
-    expect(histories.rows).toHaveLength(1);
-  });
-
-  test("Enrollment validation", async () => {
-    const courseId = 1;
-    const userId = 1;
-
-    // First enrollment succeeds
-    await EnrollmentModel.enroll(courseId, userId);
-
-    // Duplicate enrollment fails
-    await expect(EnrollmentModel.enroll(courseId, userId)).rejects.toThrow(
-      "Already enrolled in this course",
-    );
-  });
-});
-```
-
----
-
-## Conventions and Best Practices
-
-### Error Message Pattern
-
-Use `this.modelName` and the `SD()` function for consistent error messages.
-
-**BAD: Hardcoded model name**
-
-```typescript
-// findById
-if (!rows[0]) {
-  throw new NotFoundException(SD("error.entityNotFound")("Department", id));
-}
-
-// findMany
-throw new BadRequestException(SD("error.unknownSearchField")(params.search));
-```
-
-**GOOD: Using this.modelName**
-
-```typescript
-// findById - auto-detects model name
-if (!rows[0]) {
-  throw new NotFoundException(SD("notFound")(this.modelName, id));
-}
-
-// findMany - short and clear key
-throw new BadRequestException(SD("search.invalidField")(params.search));
-```
-
-**Benefits:**
-
-- DRY principle: model name managed in one place
-- Refactoring safe: error messages auto-reflect model name changes
-- Short i18n keys: `notFound`, `search.invalidField` are more concise
-
-### satisfies Keyword
-
-Use TypeScript's satisfies keyword to preserve type inference while checking types.
-
-**BAD: Loss of type inference**
-
-```typescript
-const params: RoleListParams = {
-  num: 24,
-  page: 1,
-  search: "id" as const,
-  orderBy: "id-desc" as const,
-  ...rawParams,
-};
-```
-
-**GOOD: Type check + preserved inference with satisfies**
-
-```typescript
-const params = {
-  num: 24,
-  page: 1,
-  search: "id" as const,
-  orderBy: "id-desc" as const,
-  ...rawParams,
-} satisfies RoleListParams;
-```
-
-**Benefits:**
-
-- Compile-time verification: checks that params satisfies the RoleListParams type
-- Preserved type inference: params keeps its narrowed type
-- Better IDE support: more accurate autocomplete and type checking
-
-### debug Option
-
-The debug option in executeSubsetQuery defaults to false, so it does not need to be specified explicitly.
-
-**BAD: Unnecessary debug: false**
-
-```typescript
-return this.executeSubsetQuery({
-  subset,
-  qb,
-  params,
-  enhancers,
-  debug: false, // unnecessary — it's the default
-});
-```
-
-**GOOD: Use the default**
-
-```typescript
-return this.executeSubsetQuery({
-  subset,
-  qb,
-  params,
-  enhancers,
-});
-```
-
-**When to use debug: true:**
-
-```typescript
-// Only specify when debugging
-return this.executeSubsetQuery({
-  subset,
-  qb,
-  params,
-  debug: true, // Print SQL query log
-});
-```
-
-## @stream Decorator (SSE)
-
-Creates a Server-Sent Events endpoint.
-
-```typescript
-import { stream } from "sonamu";
-import { z } from "zod";
-
-@stream({
-  type: "sse",
-  events: z.object({
-    progress: z.object({ percent: z.number() }),
-    done: z.object({ result: z.string() }),
-  }),
-  guards: ["user"],
-})
-async processStream() { ... }
-```
-
-| Option         | Description                                    | Required |
-| -------------- | ---------------------------------------------- | -------- |
-| `type`         | `"sse"` (only SSE currently supported)         | Yes      |
-| `events`       | Define event keys and payloads with Zod schema | Yes      |
-| `path`         | Custom path                                    | -        |
-| `resourceName` | Resource name                                  | -        |
-| `guards`       | Authentication/authorization guards            | -        |
-
-## @transactional Decorator
-
-Wraps the entire method in an automatic transaction. Reuses an existing transaction context if one is already active.
-
-```typescript
-import { transactional } from "sonamu";
-
-@transactional({ isolation: "serializable" })
-async transferFunds(fromId: number, toId: number, amount: number) {
-  // this.getPuri("w") automatically runs inside the transaction
-}
-```
-
-| Option      | Description                                                                                | Default |
-| ----------- | ------------------------------------------------------------------------------------------ | ------- |
-| `isolation` | Transaction isolation level (read uncommitted/read committed/repeatable read/serializable) | -       |
-| `readOnly`  | Read-only transaction                                                                      | `false` |
-| `dbPreset`  | DB preset                                                                                  | `"w"`   |