feat(ai): actions opt in to AI tools via ai: block (ADR-0011) (#1581)

Realign ADR-0011 with its original opt-in design and finalise the
implementation. An Action becomes an AI-callable tool only when it sets
`ai.exposed: true`, which requires an explicit LLM-facing `ai.description`
(distinct from the UI `label`). No heuristic auto-exposure, no label-derived
descriptions — a clean break from the first implementation's opt-out
`aiExposed` flag, which is removed outright (no compat shim; not yet shipped).

- spec: ActionAiSchema (exposed/description/category/paramHints/outputSchema/
  requiresConfirmation) + refines; remove aiExposed; extend AIToolDefinition
  with category/outputSchema/objectName/requiresConfirmation; update action.form.
- service-ai: bridge gates on opt-in, uses ai.description, merges paramHints,
  summarises outputSchema into the description, honours requiresConfirmation
  override, and warns on exposed destructive actions asserted safe.
- examples/app-todo: migrate script actions to opt-in (testbed).
- docs: rewrite ADR-0011 to Accepted/Implemented with the AI-author rationale.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

.changeset/actions-as-ai-tools.md

@@ -0,0 +1,22 @@
+---
+'@objectstack/spec': patch
+'@objectstack/service-ai': patch
+---
+
+feat(ai): actions opt in to being AI tools via an `ai:` block (ADR-0011)
+
+Realigns ADR-0011 with its original opt-in design. An Action becomes an
+AI-callable tool only when its metadata sets `ai.exposed: true`, which requires
+an explicit, LLM-facing `ai.description` (≥40 chars, distinct from the UI
+`label`). There is no heuristic auto-exposure and no description derived from
+the label — a clean break from the first implementation's opt-out `aiExposed`
+flag, which is removed (no compatibility shim; the platform has not shipped).
+
+The `ai:` block also carries `category`, `paramHints` (per-parameter JSON-Schema
+refinement), `outputSchema` (summarised into the tool description for chaining),
+and `requiresConfirmation` (overrides the destructive-action HITL default).
+`AIToolDefinition` is extended to carry `category` / `outputSchema` / `objectName`
+/ `requiresConfirmation`. The `@objectstack/service-ai` bridge
+(`action-tools.ts`) now gates on opt-in, merges `paramHints`, and emits a lint
+warning when an exposed destructive-looking action asserts itself safe via
+`ai.requiresConfirmation: false`.

docs/adr/0011-actions-as-ai-tools.md

@@ -13,6 +13,10 @@ export const CompleteTaskAction: Action = {
   locations: ['record_header', 'list_item'],
   successMessage: 'Task marked as complete!',
   refreshAfter: true,
+  ai: {
+    exposed: true,
+    description: 'Mark a todo task as complete. Use when the user says a task is done or finished.',
+  },
 };
 
 /** Mark Task as In Progress */
@@ -26,6 +30,10 @@ export const StartTaskAction: Action = {
   locations: ['record_header', 'list_item'],
   successMessage: 'Task started!',
   refreshAfter: true,
+  ai: {
+    exposed: true,
+    description: 'Mark a todo task as in progress. Use when the user says they are starting or working on a task.',
+  },
 };
 
 /** Defer Task */
@@ -87,6 +95,10 @@ export const CloneTaskAction: Action = {
   locations: ['record_header'],
   successMessage: 'Task cloned successfully!',
   refreshAfter: true,
+  ai: {
+    exposed: true,
+    description: 'Duplicate an existing todo task, copying its fields into a new task record.',
+  },
 };
 
 /** Mass Complete Tasks */
@@ -100,6 +112,10 @@ export const MassCompleteTasksAction: Action = {
   locations: ['list_toolbar'],
   successMessage: 'Selected tasks marked as complete!',
   refreshAfter: true,
+  ai: {
+    exposed: true,
+    description: 'Mark all currently selected todo tasks as complete in one bulk operation.',
+  },
 };
 
 /** Delete Completed Tasks */
@@ -118,6 +134,13 @@ export const DeleteCompletedAction: Action = {
   confirmText: 'Permanently delete all completed tasks? This cannot be undone.',
   successMessage: 'Completed tasks deleted!',
   refreshAfter: true,
+  ai: {
+    exposed: true,
+    description:
+      'Permanently delete every completed todo task. Destructive and irreversible — only after the user confirms.',
+    // confirmText + variant:'danger' default this to requiring HITL approval;
+    // it registers only when enableActionApproval is on, then routes to the queue.
+  },
 };
 
 /** Export Tasks to CSV */
@@ -131,4 +154,8 @@ export const ExportToCsvAction: Action = {
   locations: ['list_toolbar'],
   successMessage: 'Export completed!',
   refreshAfter: false,
+  ai: {
+    exposed: true,
+    description: 'Export the current list of todo tasks to a downloadable CSV file.',
+  },
 };

examples/app-todo/src/actions/task.actions.ts

@@ -1,9 +1,10 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 //
 // AI **action** integration demo — the write-side counterpart to
-// `ai-agent.test.ts`. Confirms that every `type: 'script'` action on
-// the Task object is auto-registered as an `action_<name>` tool, and
-// that the `data_chat` agent can pick the right one in plain English.
+// `ai-agent.test.ts`. Confirms that every `type: 'script'` action on the
+// Task object that opts in via `ai.exposed` (ADR-0011) is registered as an
+// `action_<name>` tool, and that the `data_chat` agent can pick the right
+// one in plain English.
 //
 // Run via: `pnpm --filter @example/app-todo test:action`
 //
@@ -189,7 +190,7 @@ import { registerTaskActionHandlers } from '../src/actions/register-handlers';
   }
 
   console.log('\n🎉 Action Demo Successful!');
-  console.log('   • Script-type actions auto-exposed as `action_*` tools');
+  console.log('   • Opted-in script actions (ai.exposed) registered as `action_*` tools');
   console.log('   • Agent routed user request to action_complete_task');
   console.log('   • Task status mutated from incomplete → completed');
   console.log('   • chat_with_tools trace persisted in ai_traces');

examples/app-todo/test/ai-action.test.ts

@@ -4,13 +4,16 @@ import { describe, it, expect, vi } from 'vitest';
 import type { Action } from '@objectstack/spec/ui';
 import {
   actionSkipReason,
+  actionToToolDefinition,
   buildApiRequestBody,
   createFetchApiClient,
   registerActionsAsTools,
   type ApiActionClient,
 } from '../tools/action-tools.js';
 import { ToolRegistry } from '../tools/tool-registry.js';
 
+// Actions are AI-exposed only by opt-in (ADR-0011), so the baseline fixture
+// carries a valid `ai` block. Tests that exercise the opt-in gate override it.
 const baseAction = (over: Partial<Action> = {}): Action =>
   ({
     name: 'do_thing',
@@ -19,6 +22,7 @@ const baseAction = (over: Partial<Action> = {}): Action =>
     target: 'doThingHandler',
     objectName: 'task',
     locations: ['record_header'],
+    ai: { exposed: true, description: 'Do the thing the user asked for on this task record.' },
     ...over,
   }) as Action;
 
@@ -52,8 +56,89 @@ describe('actionSkipReason', () => {
     expect(actionSkipReason(baseAction({ variant: 'danger' }))).toMatch(/danger/);
   });
 
-  it('respects aiExposed:false', () => {
-    expect(actionSkipReason(baseAction({ aiExposed: false }))).toMatch(/aiExposed/);
+  it('is opt-in: skips actions that did not set ai.exposed', () => {
+    expect(actionSkipReason(baseAction({ ai: undefined }))).toMatch(/not AI-exposed/);
+    expect(actionSkipReason(baseAction({ ai: { exposed: false } as never }))).toMatch(/not AI-exposed/);
+  });
+
+  it('skips an exposed action missing a description (defensive)', () => {
+    expect(
+      actionSkipReason(baseAction({ ai: { exposed: true } as never })),
+    ).toMatch(/description is missing/);
+  });
+
+  it('ai.requiresConfirmation:false lets an exposed destructive action run', () => {
+    // delete looks destructive, but the author asserts it is safe → exposed.
+    expect(
+      actionSkipReason(baseAction({
+        mode: 'delete',
+        ai: { exposed: true, description: 'Archive this task record; it is reversible from trash.', requiresConfirmation: false },
+      })),
+    ).toBeNull();
+  });
+
+  it('ai.requiresConfirmation:true gates an otherwise-safe action behind HITL', () => {
+    const a = baseAction({
+      ai: { exposed: true, description: 'Update the task title to the value the user supplied.', requiresConfirmation: true },
+    });
+    expect(actionSkipReason(a)).toMatch(/requires confirmation/);
+    expect(
+      actionSkipReason(a, {
+        enableActionApproval: true,
+        aiService: { proposePendingAction: async () => ({ id: 'x' }) },
+      }),
+    ).toBeNull();
+  });
+});
+
+describe('actionToToolDefinition — ai: block translation', () => {
+  it('returns null when not exposed', () => {
+    expect(actionToToolDefinition(baseAction({ ai: undefined }), undefined, new Map())).toBeNull();
+  });
+
+  it('uses ai.description and carries category/objectName/requiresConfirmation', () => {
+    const def = actionToToolDefinition(
+      baseAction({ ai: { exposed: true, description: 'Triage a support case and suggest a priority and queue.', category: 'analytics' } }),
+      undefined,
+      new Map(),
+    );
+    expect(def).not.toBeNull();
+    expect(def!.description).toContain('Triage a support case');
+    expect(def!.category).toBe('analytics');
+    expect(def!.objectName).toBe('task');
+    expect(def!.requiresConfirmation).toBe(false);
+  });
+
+  it('summarises ai.outputSchema into the description and carries it through', () => {
+    const outputSchema = {
+      type: 'object',
+      properties: { priority: { type: 'string' }, queue: { type: 'string' } },
+    };
+    const def = actionToToolDefinition(
+      baseAction({ ai: { exposed: true, description: 'Triage a support case and return a structured suggestion.', outputSchema } }),
+      undefined,
+      new Map(),
+    );
+    expect(def!.outputSchema).toEqual(outputSchema);
+    expect(def!.description).toMatch(/Returns an object with: priority, queue\./);
+  });
+
+  it('merges ai.paramHints into the parameter JSON Schema', () => {
+    const def = actionToToolDefinition(
+      baseAction({
+        params: [{ name: 'priority', type: 'text' }],
+        ai: {
+          exposed: true,
+          description: 'Set the priority on the task record to one of the allowed values.',
+          paramHints: { priority: { description: 'One of P0-P3.', enum: ['P0', 'P1', 'P2', 'P3'] } },
+        },
+      }),
+      undefined,
+      new Map(),
+    );
+    const props = (def!.parameters as { properties: Record<string, Record<string, unknown>> }).properties;
+    expect(props.priority.enum).toEqual(['P0', 'P1', 'P2', 'P3']);
+    expect(props.priority.description).toBe('One of P0-P3.');
   });
 });
 
@@ -372,3 +457,33 @@ describe('actionRequiresApproval + HITL queue routing', () => {
     expect((result as any).result).toEqual({ deleted: true });
   });
 });
+
+describe('lint guardrail — asserted-safe destructive actions', () => {
+  it('registers but warns when a destructive action sets ai.requiresConfirmation:false', async () => {
+    const reg = new ToolRegistry();
+    const action = baseAction({
+      name: 'archive_task',
+      mode: 'delete',
+      type: 'script',
+      target: 'archiveTaskHandler',
+      locations: [],
+      params: [],
+      ai: {
+        exposed: true,
+        description: 'Archive this task record; the operation is reversible from the trash.',
+        requiresConfirmation: false,
+      },
+    } as Partial<Action>);
+    const objects = [{ name: 'task', label: 'Task', fields: {}, actions: [action] }];
+    const { registered, skipped, warnings } = await registerActionsAsTools(reg, {
+      metadata: { listObjects: async () => objects } as never,
+      dataEngine: { find: async () => [], executeAction: async () => ({ ok: true }) } as never,
+    } as never);
+
+    expect(skipped).toEqual([]);
+    expect(registered).toEqual(['action_archive_task']);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].action).toBe('archive_task');
+    expect(warnings[0].warning).toMatch(/without human approval/);
+  });
+});

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

@@ -151,9 +151,9 @@ export const AiPendingActionObject = ObjectSchema.create({
       variant: 'primary',
       confirmText: 'Approve and execute this action now?',
       successMessage: 'Action approved and executed.',
-      // The approval click is the operator's authorisation gesture —
-      // the LLM must not be allowed to bypass HITL by approving itself.
-      aiExposed: false,
+      // Human-only by design: not opted into AI (no `ai.exposed`). The approval
+      // click is the operator's authorisation gesture — the LLM must not be
+      // able to bypass HITL by approving itself.
     },
     {
       name: 'reject_pending_action',
@@ -165,7 +165,7 @@ export const AiPendingActionObject = ObjectSchema.create({
       variant: 'danger',
       confirmText: 'Reject this pending action? It will not be executed.',
       successMessage: 'Action rejected.',
-      aiExposed: false,
+      // Human-only by design: not opted into AI (no `ai.exposed`).
     },
   ],
 

packages/services/service-ai/src/objects/ai-pending-action.object.ts

@@ -666,7 +666,7 @@ export class AIServicePlugin implements Plugin {
             const apiBaseUrl =
               this.options.apiActionBaseUrl ?? process.env.OS_AI_ACTION_API_BASE_URL;
             const apiHeaders = this.options.apiActionHeaders;
-            const { registered, skipped } = await registerActionsAsTools(
+            const { registered, skipped, warnings } = await registerActionsAsTools(
               this.service.toolRegistry,
               {
                 metadata: metadataService,
@@ -689,6 +689,9 @@ export class AIServicePlugin implements Plugin {
                 { skipped },
               );
             }
+            for (const w of warnings) {
+              ctx.logger.warn(`[AI] action '${w.action}': ${w.warning}`);
+            }
           } catch (err) {
             ctx.logger.warn(
               '[AI] Failed to register action tools',