feat(ai): add HITL approval queue for dangerous actions

Author: os-zhuang

.changeset/plugin-auth-webcontainer-scrypt.md

@@ -0,0 +1,24 @@
+---
+"@objectstack/plugin-auth": minor
+---
+
+WebContainer (StackBlitz) signup compatibility: `AuthManager` now auto-detects
+WebContainer runtimes at construction time and swaps better-auth's default
+`node:crypto.scrypt`-based password hasher for the pure-JS hasher from
+`@better-auth/utils/password` (which uses `@noble/hashes/scrypt` under the
+hood).
+
+**Why:** WebContainer's `node:crypto` polyfill ships an incomplete `scrypt`
+implementation that throws `TypeError: y.run is not a function` on every
+signup, blocking template demos on StackBlitz. The pure-JS implementation is
+byte-compatible with the Node hasher (same scrypt params, same `salt:keyHex`
+storage format), so accounts created under either hasher remain mutually
+verifiable — no migration, no template changes.
+
+**Scope:** detection short-circuits to `undefined` on real Node, so production
+deployments are completely unaffected — the JS fallback module is only
+dynamically imported when one of `process.versions.webcontainer`,
+`SHELL` containing `jsh`, or `STACKBLITZ` env is present.
+
+Templates (`@template/todo`, `@template/contracts`, …) require no changes;
+the fix lives entirely inside `@objectstack/plugin-auth`.

.changeset/v5-ai-hitl-approval.md

@@ -0,0 +1,46 @@
+---
+'@objectstack/service-ai': minor
+'@objectstack/spec': patch
+---
+
+**Actions-as-tools Phase 3 — Human-In-The-Loop approval queue.**
+
+Dangerous declarative actions (`confirmText`, `mode:'delete'`, `variant:'danger'`) can now be exposed to the LLM safely. Instead of being skipped outright, they are registered as tools whose handler enqueues a pending request and returns `{ status: 'pending_approval', pendingActionId }` to the model. A human approves (or rejects) from Studio's pending-actions inbox; the service then re-runs the exact same dispatcher.
+
+### New surface
+
+- New system object `ai_pending_actions` (id, conversation_id?, message_id?, object_name, action_name, tool_name, tool_input, status [`pending`|`approved`|`executed`|`failed`|`rejected`], result?, error?, rejection_reason?, proposed_by, decided_by?, proposed_at, decided_at?).
+- New built-in Studio view `AiPendingActionView` with `pending` / `executed` / `rejected` / `failed` sub-views and per-row **Approve** / **Reject** API actions.
+- New methods on `IAIService` (all optional, gated on a wired `IDataEngine`):
+  - `proposePendingAction(input) → { id }`
+  - `approvePendingAction(id, actorId) → { status, result?, error? }`
+  - `rejectPendingAction(id, actorId, reason?)`
+  - `listPendingActions(filter?) → PendingActionRow[]`
+- New exported types: `PendingActionStatus`, `ProposePendingActionInput`, `PendingActionRow`.
+- New REST routes (auth required):
+  - `GET    /api/v1/ai/pending-actions`           (`ai:read`)
+  - `GET    /api/v1/ai/pending-actions/:id`       (`ai:read`)
+  - `POST   /api/v1/ai/pending-actions/:id/approve`  (`ai:approve`)
+  - `POST   /api/v1/ai/pending-actions/:id/reject`   (`ai:approve`)
+- New exported predicate `actionRequiresApproval(action)` for Studio's exposure surface.
+
+### Wiring
+
+`AIServicePluginOptions` gains `enableActionApproval?: boolean` (default `false`). When `true` and an `IDataEngine` is available, dangerous actions are registered and routed through the queue.
+
+```ts
+kernel.use(new AIServicePlugin({
+  enableActionApproval: true,           // opt in
+  apiActionBaseUrl: 'http://localhost:3000',
+}));
+```
+
+### Internals
+
+- `actionSkipReason()` accepts `enableActionApproval` + `aiService` in its ctx and stops returning `"requires confirmation"` / `"mode='delete'"` / `"variant='danger'"` when HITL is wired.
+- `registerActionsAsTools()` pre-registers a *bypass-approval* dispatcher per dangerous tool via `aiService.registerPendingActionDispatcher(toolName, fn)`; approval calls back into the same code path with `enableActionApproval` flipped off, so a single handler implementation serves both proposal and execution.
+- `createActionToolHandler()` short-circuits to `proposePendingAction()` when `enableActionApproval && actionRequiresApproval(action) && ctx.aiService?.proposePendingAction`.
+
+### Out of scope (deferred)
+
+Slack/email notifications, approver routing (any signed-in user can approve in v1), auto-expiry of pending requests, resuming the same LLM turn after approval (operators get a fresh assistant message instead).

content/docs/guides/ai-capabilities.mdx

@@ -12,6 +12,7 @@ Complete guide to leveraging AI agents, RAG pipelines, and intelligent automatio
 1. [AI Architecture](#ai-architecture)
 2. [AI Agents](#ai-agents)
 3. [Actions as Tools (auto-exposed)](#actions-as-tools-auto-exposed)
+   - [Human-In-The-Loop approval](#human-in-the-loop-approval)
 4. [RAG Pipelines](#rag-pipelines)
 5. [Natural Language Queries](#natural-language-queries)
 6. [Predictive Analytics](#predictive-analytics)
@@ -371,7 +372,7 @@ The AI runtime walks every registered object's `actions[]` and exposes the ones
 | `api` | HTTP call to `action.target` via `ApiActionClient` (default: `fetch`) | `apiBaseUrl` (or a custom `apiClient`) |
 | `flow` | `IAutomationService.execute(target, { triggerData })` | `automation` service registered |
 
-Studio-only types (`url`, `modal`, `form`) and any action with `confirmText`, `mode: 'delete'`, or `variant: 'danger'` are skipped — those require Phase-3 HITL approval. Owners can also opt out per action with `aiExposed: false`.
+Studio-only types (`url`, `modal`, `form`) are always skipped. Dangerous actions — those with `confirmText`, `mode: 'delete'`, or `variant: 'danger'` — are skipped **by default**, but can be opted into the [HITL approval queue](#human-in-the-loop-approval) so an operator authorises every call. Owners can also opt out per action with `aiExposed: false`.
 
 ### Wiring it up
 
@@ -405,6 +406,33 @@ For api actions, the request body is built from three sources (last wins):
 
 `registerActionsAsTools()` returns `{ registered, skipped }`. Studio surfaces the skipped list with reasons (e.g. `"no apiClient or apiBaseUrl configured"`, `"mode='delete' — destructive"`) so action authors can see at a glance whether their action will be LLM-callable.
 
+### Human-In-The-Loop approval
+
+Destructive actions are too risky to let the LLM execute autonomously, but locking them away entirely defeats agentic UX. The HITL queue strikes the balance: the LLM gets to **propose** the call, a human gets to **approve** it.
+
+Enable the queue via the plugin option (default: off):
+
+```typescript
+kernel.use(
+  new AIServicePlugin({
+    enableActionApproval: true,
+    apiActionBaseUrl: process.env.OS_AI_ACTION_API_BASE_URL,
+  }),
+);
+```
+
+When the LLM picks an approval-gated tool (e.g. `action_delete_task`), the runtime:
+
+1. Persists an `ai_pending_actions` row with `status:'pending'`, `tool_input`, `proposed_by`, etc.
+2. Returns `{ status: 'pending_approval', pendingActionId }` to the model so it can summarise (e.g. "I've requested approval to delete task #42.").
+3. The operator sees the proposal in the **AI Pending Actions** Studio inbox.
+4. Clicking **Approve** calls `POST /api/v1/ai/pending-actions/:id/approve` (`ai:approve` permission). The service looks up the pre-registered dispatcher and executes the action with HITL routing disabled, so the same code path runs. The row transitions to `executed` (or `failed` if dispatch threw).
+5. Clicking **Reject** calls `POST /api/v1/ai/pending-actions/:id/reject` with an optional reason.
+
+The queue is exposed via four REST endpoints (`GET`, `GET/:id`, `POST/:id/approve`, `POST/:id/reject`) and via `IAIService.{proposePendingAction,approvePendingAction,rejectPendingAction,listPendingActions}` for programmatic use.
+
+**Why a dedicated queue (not the multi-step `IApprovalService`)?** AI tool-call HITL is ephemeral: subject is the proposed *call*, not a stable record state; there's no predefined process; operators expect single-click yes/no. The pending-action queue is a thin write log + dispatcher map that delivers that UX without dragging in process-engine overhead.
+
 ---
 
 ## RAG Pipelines

content/docs/references/ai/skill.mdx

@@ -37,7 +37,7 @@ const result = Skill.parse(data);
 | **label** | `string` | ✅ | Skill display name |
 | **description** | `string` | optional | Skill description |
 | **instructions** | `string` | optional | LLM instructions when skill is active |
-| **tools** | `string[]` | ✅ | Tool names belonging to this skill |
+| **tools** | `string[]` | ✅ | Tool names belonging to this skill (supports trailing wildcard, e.g. `action_*`) |
 | **triggerPhrases** | `string[]` | optional | Phrases that activate this skill |
 | **triggerConditions** | `Object[]` | optional | Programmatic activation conditions |
 | **permissions** | `string[]` | optional | Required permissions or roles |

packages/plugins/plugin-auth/package.json

@@ -19,6 +19,7 @@
   },
   "dependencies": {
     "@better-auth/oauth-provider": "^1.6.11",
+    "@better-auth/utils": "^0.4.0",
     "@objectstack/core": "workspace:*",
     "@objectstack/platform-objects": "workspace:*",
     "@objectstack/spec": "workspace:*",

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -154,6 +154,7 @@ export class AuthManager {
   private async createAuthInstance(): Promise<Auth<any>> {
     const { betterAuth } = await import('better-auth');
     const plugins = await this.buildPluginList();
+    const passwordHasher = await this.resolvePasswordHasher();
     const betterAuthConfig: BetterAuthOptions = {
       // Base configuration
       secret: this.config.secret || this.generateSecret(),
@@ -217,6 +218,7 @@ export class AuthManager {
       // Email and password configuration
       emailAndPassword: {
         enabled: this.config.emailAndPassword?.enabled ?? true,
+        ...(passwordHasher ? { password: passwordHasher } : {}),
         ...(this.config.emailAndPassword?.disableSignUp != null
           ? { disableSignUp: this.config.emailAndPassword.disableSignUp } : {}),
         ...(this.config.emailAndPassword?.requireEmailVerification != null
@@ -360,6 +362,42 @@ export class AuthManager {
     return betterAuth(betterAuthConfig);
   }
 
+  /**
+   * Detect WebContainer (StackBlitz) and swap in a pure-JS scrypt hasher.
+   *
+   * better-auth defaults to `@better-auth/utils/password.node`, which calls
+   * `node:crypto.scrypt`. WebContainer polyfills that API incompletely and
+   * signup throws `TypeError: y.run is not a function`. The pure-JS variant
+   * at `@better-auth/utils/password` uses `@noble/hashes/scrypt` with
+   * identical params (N=16384, r=16, p=1, dkLen=64) and emits the same
+   * `{salt}:{keyHex}` format, so existing hashes remain verifiable.
+   *
+   * Returns `undefined` outside WebContainer so production deployments keep
+   * the native (fast) hasher and never load the JS fallback.
+   */
+  private async resolvePasswordHasher(): Promise<
+    { hash: (password: string) => Promise<string>; verify: (args: { hash: string; password: string }) => Promise<boolean> } | undefined
+  > {
+    const isWebContainer =
+      typeof globalThis !== 'undefined' &&
+      (Boolean((globalThis as any).process?.versions?.webcontainer) ||
+        Boolean((globalThis as any).process?.env?.SHELL?.includes?.('jsh')) ||
+        Boolean((globalThis as any).process?.env?.STACKBLITZ));
+    if (!isWebContainer) return undefined;
+    try {
+      const mod = await import('@better-auth/utils/password');
+      return {
+        hash: (password: string) => mod.hashPassword(password),
+        verify: ({ hash, password }) => mod.verifyPassword(hash, password),
+      };
+    } catch (err: any) {
+      console.warn(
+        `[AuthManager] WebContainer detected but pure-JS password hasher unavailable: ${err?.message ?? err}. Falling back to default.`,
+      );
+      return undefined;
+    }
+  }
+
   /**
    * Build the list of better-auth plugins based on AuthPluginConfig flags.
    *

packages/services/service-ai/src/__tests__/action-tools.test.ts

@@ -283,3 +283,92 @@ describe('registerActionsAsTools — api + flow dispatch', () => {
     expect(parsed.error).toMatch(/smtp down/);
   });
 });
+
+describe('actionRequiresApproval + HITL queue routing', () => {
+  it('skips dangerous actions when approval is NOT wired', () => {
+    const a = baseAction({ mode: 'delete' });
+    // No approval ctx → skipped
+    expect(actionSkipReason(a)).toMatch(/delete/);
+    expect(actionSkipReason(a, { enableActionApproval: false })).toMatch(/delete/);
+  });
+
+  it('registers dangerous actions when approval IS wired', () => {
+    const a = baseAction({ mode: 'delete' });
+    expect(
+      actionSkipReason(a, {
+        enableActionApproval: true,
+        aiService: { proposePendingAction: async () => ({ id: 'x' }) },
+      }),
+    ).toBeNull();
+  });
+
+  it('routes invocation to proposePendingAction + pre-registers dispatcher', async () => {
+    const reg = new ToolRegistry();
+    const propose = vi.fn(async (input: unknown) => {
+      void input;
+      return { id: 'pa_42' };
+    });
+    const dispatchers = new Map<string, (input: unknown) => Promise<unknown>>();
+    const registerDispatcher = vi.fn((name: string, fn: (input: unknown) => Promise<unknown>) => {
+      dispatchers.set(name, fn);
+    });
+
+    let executed = false;
+    const action = baseAction({
+      name: 'delete_task',
+      mode: 'delete',
+      type: 'script',
+      target: 'deleteTaskHandler',
+      locations: [],
+      params: [],
+    } as Partial<Action>);
+    const objects = [{ name: 'task', label: 'Task', fields: {}, actions: [action] }];
+
+    const { registered, skipped } = await registerActionsAsTools(reg, {
+      metadata: { listObjects: async () => objects } as never,
+      dataEngine: {
+        find: async () => [],
+        executeAction: async () => {
+          executed = true;
+          return { deleted: true };
+        },
+      } as never,
+      enableActionApproval: true,
+      aiService: {
+        proposePendingAction: propose,
+        registerPendingActionDispatcher: registerDispatcher,
+      },
+    } as never);
+
+    expect(skipped).toEqual([]);
+    expect(registered).toEqual(['action_delete_task']);
+    expect(registerDispatcher).toHaveBeenCalledWith('action_delete_task', expect.any(Function));
+
+    // LLM invokes the tool → should NOT execute, should queue.
+    const r = await reg.execute({
+      type: 'tool-call',
+      toolCallId: 't1',
+      toolName: 'action_delete_task',
+      input: { recordId: 'rec_1' },
+    } as never);
+    const env = JSON.parse((r.output as { value: string }).value);
+    expect(env.status).toBe('pending_approval');
+    expect(env.pendingActionId).toBe('pa_42');
+    expect(executed).toBe(false);
+    expect(propose).toHaveBeenCalledTimes(1);
+    const proposeArg = propose.mock.calls[0][0] as any;
+    expect(proposeArg.objectName).toBe('task');
+    expect(proposeArg.actionName).toBe('delete_task');
+    expect(proposeArg.toolName).toBe('action_delete_task');
+    expect(proposeArg.toolInput).toEqual({ recordId: 'rec_1' });
+
+    // Approval pathway: registered dispatcher should bypass HITL.
+    const dispatcher = dispatchers.get('action_delete_task');
+    expect(dispatcher).toBeDefined();
+    const result = await dispatcher!({ recordId: 'rec_1' });
+    expect(executed).toBe(true);
+    // Dispatcher returns parsed envelope (helps AIService store structured result).
+    expect((result as any).ok).toBe(true);
+    expect((result as any).result).toEqual({ deleted: true });
+  });
+});