create-flowdular 0.2.4 → 0.2.6

package/agent-template/.ai/skills/variables/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: variables
+description: >-
+  Build variable-aware fields and templates on the {{ }} contract, the scope
+  mask, and server-side resolution, with agents.core as the worked example.
+roles:
+  - frontend-engineer
+  - ux-designer
+  - agentic-engineer
+  - backend-engineer
+  - module-executor
+when: A field must let a value embed {{ variable }} tokens filled from other fields, the request context, or another module.
+---
+
+# Variables (templating and linked fields)
+
+A variable field lets a stored value embed `{{ key }}` tokens that are filled at
+run time from context or another module's data. The contract is pure and lives
+in `@flowdular/sdk/contracts` (`packages/contracts/src/variables.ts`); the fields are
+presentational primitives in `@flowdular/sdk/ui`; resolution happens on the server
+before the consumer sees the text. `agents.core` is the worked example: an agent
+author writes instructions as a template and the run snapshot carries the
+resolved text.
+
+## The `{{ }}` contract
+
+`VariableDefinition { key, label, kind, scope?, sample?, description? }` is one
+offerable variable. `kind` is `text | number | date | money | identifier`.
+`key` is a dot path whose segments start lowercase and may continue in
+camelCase (`context.user.displayName`), matched by `VARIABLE_KEY_PATTERN` /
+`isVariableKey`.
+
+- `extractVariables(template)`: the distinct trimmed `{{ key }}` tokens, in
+  first-seen order.
+- `validateTemplate(template, available, allowedScopes?)`: `{ unknown, forbidden }`.
+  `unknown` are tokens not in `available`; `forbidden` are tokens whose def
+  declares a `scope` not present in `allowedScopes` (omit `allowedScopes` to skip
+  the scope check).
+- `resolveTemplate(template, values, { onMissing })`: substitutes each
+  `{{ key }}` with `values[key]`. `onMissing` is `keep` (default, leave the token
+  verbatim) or `blank`.
+- `tokenizeTemplate(template)`: the segments the UI overlay highlights; the
+  `text` fields concatenate back to the exact input.
+
+Rules the resolver guarantees: tokens are `{{ key }}` with optional inner spaces;
+`\{{` outputs a literal `{{`; substitution is a single pass, so a value that
+itself looks like a token is emitted verbatim (never recursive); only own,
+string keys resolve, so prototype keys (`__proto__`, `toString`) never resolve.
+No eval, no expressions, only key substitution.
+
+## The scope mask
+
+`VariableDefinition.scope` is the permission required to read the source. A
+variable is offered and resolved only when the principal holds that scope:
+
+- The UI fields never fetch and never check scopes. The caller passes
+  `variables` already filtered to what this principal may use, so a variable the
+  principal cannot read is simply absent from the menu and highlights as an error
+  pill if typed.
+- On the server, filter the definition list by the principal's scopes before
+  building `values`, or call `validateTemplate(..., allowedScopes)` and refuse a
+  template whose `forbidden` is non-empty. A scope-less variable
+  (`context.*`) is always allowed.
+
+## The UI fields (`@flowdular/sdk/ui`)
+
+`VariableTextarea` (multiline), `VariableInput` (single line), and
+`VariableSelect` (one literal option or one variable token) are presentational.
+All take `value`, `onInput`, `variables: readonly VariableDefinition[]`, optional
+`sampleValues?: Record<string,string>`, required translated `label` (accessible
+name), `name` (so a `FormData` submit still captures it), `required`, `disabled`,
+and `error`. Input and textarea also require translated `insertLabel`,
+`variablesLabel`, and `emptyLabel`; the shared primitive has no English copy to
+fall back to. Select takes `options: readonly VariableSelectLiteralOption[]` and
+requires translated `literalGroupLabel` and `variablesGroupLabel`. A caller also
+localizes every `VariableDefinition.label` before passing the definitions, since
+that label is visible in the picker.
+
+- The `braces` affordance (a `{}` icon in `ICON_PATHS`) opens a menu of the
+  available variables with label, key, and current or sample value; picking one
+  inserts `{{ key }}` at the caret. Typing `{{` opens the same menu filtered by
+  what follows; ArrowUp/Down and Enter pick, Escape closes.
+- Tokens are highlighted by an overlay layer (`tokenizeTemplate`) sitting behind
+  a transparent control, so `{{ key }}` reads as a pill while the real value
+  stays plain text; an unknown or forbidden token gets the error pill. All
+  color comes from tokens; measurement is client-only in an effect, so SSR is
+  safe. See `packages/ui/src/components/VariableField.tsrx` and its wrappers.
+- `VariableSelect` stays a native `<select>`. Literal values and allowed
+  `{{ key }}` tokens are real `<option>` values, so keyboard navigation,
+  validation, disabled state, accessible naming, and `FormData` submission keep
+  browser semantics. Samples appear only in option labels. The component never
+  resolves the selected token.
+
+Keep the fields presentational: the caller supplies `variables` and
+`sampleValues`, the component never fetches.
+
+The platform variable registry (`@flowdular/sdk/kernel`) registers definitions and
+their execution-time resolvers. Reach the shared instance with
+`platformVariableRegistry(context.capabilities)`. `list(scopes)` requires an
+explicit permission snapshot and is the only
+definition list a server sends to a field. `resolve(template, request)` takes a
+trusted tenant id, actor, immutable permission snapshot, `AbortSignal`, explicit
+record bindings and optional values owned by the consumer. It validates the
+whole template before invoking a source. An unknown token, missing scope,
+missing binding, aborted request, unavailable record, or source failure is a
+refusal. Source exceptions are replaced with a generic error so SQL, provider,
+and record details do not cross the module boundary.
+
+The source declares `requiredBindings` per variable. For example, `party.name`
+requires `partyId`; the resolver receives that id explicitly and asks the
+parties public capability or read tool under `request.tenantId`. It never infers
+a record from browser state and never reads the parties database. Local form
+values go in `request.values`, while cross-module values must come from the
+registered resolver. The resolved text is returned to the server consumer only;
+the raw template remains stored.
+
+## Server-side resolution rule
+
+Resolve the template before the consumer sees it, and keep the raw template
+stored. The stored record keeps the `{{ }}` template; the run or send snapshot
+carries the resolved text. Never resolve in the client and never store the
+resolved text back onto the definition.
+
+Worked example in `agents.core`:
+
+- `modules/agents/src/domain/context-variables.ts` declares
+  `AGENT_CONTEXT_VARIABLES` (`context.tenantName`, `context.today`,
+  `context.user.displayName`, `context.user.email`, all scope-less) and
+  `agentContextValues(input)` that builds their values from the run's
+  tenant/principal/date.
+- `AgentService.enqueueRun` (`services/agent-service.ts`) resolves
+  `agent.instructions` with `resolveTemplate` against those values before it
+  builds the instruction snapshot; the stored definition is untouched. The
+  endpoint (`api/endpoints.ts`) supplies the tenant name and principal from the
+  request; `today` comes from the queue timestamp.
+- `AgentDefinitionForm.tsrx` feeds `VariableTextarea` the context variable list
+  and sample values, so an author gets the menu and highlighting.
+
+## Adding a variable source via a capability or tool
+
+Business-data variables (for example `{{ party.name }}`) resolve through a
+public capability or an agent read tool owned by the source module:
+
+1. Declare the `VariableDefinition` with `scope` equal to the source tool's
+   `requiredPermissions` (`AgentTool` in `packages/harness/src/runtime.ts`). The
+   tool's permission is the mask: one source of truth, no parallel table.
+2. Register the source on the shared registry during module composition. Declare
+   the record id in `requiredBindings`; do not accept a tenant binding.
+3. Offer it only through `registry.list(principal.scopes)`. The UI fields take
+   this already-filtered list and never fetch.
+4. Call `registry.resolve` on the server with the trusted tenant, actor,
+   permission snapshot, signal, and explicit bindings. The source invokes only
+   its owning public capability or read tool and maps the bounded result to
+   strings. The registry refuses before the source runs if the scope or binding
+   is absent.
+
+`automations.core` is the live cross-module example. `agent.name` requires the
+schedule's explicit `agentId`, and its resolver calls the `agents.run-queue`
+capability with the active tenant. A binding containing an agent from another
+tenant resolves to no record and the run is refused. The schedule keeps the raw
+template; only the queued run receives the resolved input.
+
+Register a new tool with the `agent-tool-design` skill; this skill covers only
+how its output becomes a resolvable variable.

package/agent-template/.ai/skills/workflow-development/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: workflow-development
+description: >-
+  Build, publish, invoke, and test a workflows.core DAG through its typed graph
+  and public execution capability without bypassing agent, action, tenant, or
+  audit boundaries.
+roles:
+  - agentic-engineer
+  - backend-engineer
+  - frontend-engineer
+  - module-executor
+when: A brief asks for a workflow, pipeline, canvas node, workflow action, or a module feature that starts a workflow.
+---
+
+# Build and integrate an agentic workflow
+
+`workflows.core` owns durable directed acyclic workflows. A workflow coordinates
+pinned agent revisions, deterministic gates, schema validators, registered
+module actions, data mappings, and terminal output. It does not own schedules or
+webhook secrets. Those remain optional concerns of `automations.core`.
+
+Read `docs/adr/0006-agentic-workflows.md`, the approved
+`modules/workflows/spec/module.yaml`, and the contracts in
+`modules/workflows/src/domain/types.ts` before changing a workflow surface.
+
+## Pick the correct extension point
+
+- A workflow definition belongs in `workflows.core` and is edited through its
+  API or canvas. Do not hardcode a tenant workflow in source.
+- A business operation that a workflow may call is a versioned agent action.
+  Register it through the agents action catalog. If missing, implement it in a
+  separate `agent-tool-design` phase with permission, input, output, timeout,
+  idempotency and audit tests before returning to workflow integration.
+- A business module that starts a workflow resolves
+  `workflows.execution.v1` from `context.capabilities`. It never imports a
+  workflow repository or database.
+- A schedule or signed webhook remains in `automations.core`. Its optional
+  bridge invokes the workflow capability with a service actor and a separate
+  schedule or webhook origin.
+- If the workflow module is absent, the capability registry returns `null`.
+  Hide an optional feature or return a clear stable refusal.
+
+## Graph contract
+
+Version one is a bounded DAG. The graph contains:
+
+- `input`: accepts the invocation envelope.
+- `agent`: calls one exact immutable agent revision and validates structured
+  output.
+- `agent-decision`: produces one schema-valid `pass` or `fail` outcome.
+- `gate`: evaluates the versioned allowlisted logic language.
+- `validator`: validates an envelope against a pinned JSON schema.
+- `action`: calls one exact registered action contract version.
+- `merge`: waits for all declared incoming paths.
+- `output`: settles the workflow with a typed result.
+
+Every port names a schema. Every edge connects compatible ports. Mappings are
+declarative literals, JSON pointer paths, or templates with explicit variable
+bindings. Never add JavaScript, dynamic imports, shell commands, downloaded
+code, arbitrary expressions, or hidden provider decisions to graph data.
+
+The hard limits live in `WORKFLOW_LIMITS` in
+`modules/workflows/src/domain/types.ts`. Validation must reject a cycle,
+dangling edge, unreachable node, missing terminal output, incompatible port,
+missing exact dependency, oversized graph, or unsupported action risk before
+publication.
+
+## Revisions and publication
+
+Draft saves use optimistic concurrency through `expectedRevision`. A successful
+save creates the next draft revision. A conflict never overwrites another
+editor.
+
+Publication:
+
+1. Validates and compiles the graph.
+2. Resolves exact agent revisions and exact action contract versions.
+3. Rejects missing, archived, incompatible, external, or destructive
+   dependencies.
+4. Stores an immutable content-addressed published revision.
+5. Leaves earlier revisions and their run evidence unchanged.
+
+Never replace a pinned dependency with its latest version during execution.
+Editing after publication creates another draft.
+
+## Execution modes
+
+Use the smallest mode that proves the change:
+
+- Dry-run validates a draft and returns issues, compiled order, references,
+  permissions, checksum, and limits. It creates no run and invokes nothing.
+- Simulation persists a run history but uses fixtures for nondeterministic
+  nodes. It advances virtual time without sleeping and never calls a provider,
+  action, or business mutation.
+- Live runs only published revisions. It may call pinned agents and approved
+  read or workspace-write actions under the initiating permission snapshot.
+
+Do not disguise simulation as live execution. Do not use live mode to test an
+invalid draft.
+
+## Invoke a published workflow from a module
+
+Resolve the capability at request or service call time, after platform
+composition has completed:
+
+```ts
+import {
+	WORKFLOW_EXECUTION_CAPABILITY,
+	type WorkflowExecutionCapability,
+} from '@flowdular/sdk/modules/workflows/server';
+
+const workflows = context.capabilities.get<WorkflowExecutionCapability>(
+	WORKFLOW_EXECUTION_CAPABILITY,
+);
+if (!workflows) throw new ModuleError('WORKFLOWS_UNAVAILABLE');
+
+const accepted = await workflows.enqueue(
+	{
+		workflowKey: 'catalog-enrichment',
+		input: { itemId },
+		idempotencyKey: `catalog:${itemId}:${version}`,
+	},
+	{
+		tenantId,
+		actor,
+		origin: {
+			kind: 'module',
+			moduleId: 'catalog.core',
+			operationId: 'catalog.enrichment.start',
+		},
+		permissionSnapshot,
+	},
+);
+```
+
+The module manifest declares `workflows.core` only when workflow support is a
+required feature. An optional integration belongs in a small bridge module that
+depends on both sides. Do not duplicate the capability interface locally to
+avoid a dependency declaration.
+
+Trusted context and business input are separate. Tenant, actor, origin, and
+permission snapshot never come from the request body. The idempotency key is
+stable for one logical operation. Reusing it with different input is a
+conflict, not a second run.
+
+## Actor and permission rules
+
+- A user action uses the real user actor.
+- A tool invoked by an agent uses the real agent actor and child run
+  correlation supplied by `AgentToolContext`.
+- A schedule or webhook uses a service actor whose `configuredBy` is the real
+  user who configured it. Origin stays `schedule` or `webhook`.
+- A workflow definition grants no scope. Live execution intersects the caller
+  snapshot with each node's agent or action requirements.
+- A cross-tenant id, foreign cursor, missing scope, absent dependency, or
+  mismatched action version is refused before data or provider work.
+
+## History, recovery, and cancellation
+
+The browser observes execution. It never owns execution. Enqueue persists the
+run before returning. Workers use leases and recover expired work from stored
+node state, child ids, and stable side-effect idempotency keys.
+
+Every transition appends an ordered schema-versioned event. Run, node,
+attempt, and edge states are separate projections. `pass` and `fail` are normal
+outcome ports, not technical statuses.
+
+Cancellation is durable and cooperative. It prevents new nodes, asks the
+current child agent or action to cancel, records whether it acknowledged, and
+ignores late output for routing while keeping its safe evidence.
+
+History responses contain redacted bounded evidence. They never expose provider
+credentials, session tokens, hidden reasoning, encrypted payload blobs, or
+unrestricted request bodies.
+
+## Required tests
+
+For a graph or runtime change, prove:
+
+1. Deterministic compile order and rejection of cycles, dangling edges,
+   incompatible ports, unreachable nodes, and missing output.
+2. Tenant isolation plus one unauthenticated and one unscoped refusal for every
+   endpoint group.
+3. Exact agent and action revision refusal with no latest-version fallback.
+4. Dry-run produces no run, provider call, action call, or business write.
+5. Simulation uses fixtures and virtual duration with no real wait.
+6. Live enqueue is idempotent and persists before acceptance.
+7. Recovery before and after child enqueue does not duplicate work.
+8. Retry records the chosen delay before waiting and reuses the side-effect
+   idempotency key.
+9. Cancellation prevents downstream work and records late results safely.
+10. Event replay, cursor binding, payload redaction, retention, usage, cost,
+    and audit hash-chain integrity.
+11. The canvas shows validation, loading, empty, error, denied, simulation,
+    live, cancelled, and recovered states, including small-screen read mode.
+
+Run the module typecheck and tests, `pnpm flowdular module validate`, then the
+full `pnpm verify`. For a new module integration, update its approved spec and
+move `specVersion`, `module.json` version, and package version together.

package/agent-template/.claude/skills/agent-tool-design/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: agent-tool-design
+description: >-
+  Register an API or CLI tool that lets business agents act on a module, with
+  the real harness, permission, idempotency, audit, and test contract.
+---
+# Design and register an agent tool
+
+A module lets agents act on it by registering tools during composition. A tool
+wraps one service operation, takes the tenant from the run context, reuses the
+service validation, bounds its output, and declares the exact permission the
+matching endpoint requires. `parties.core` and `catalog.core` are the reference
+implementations.
+
+This skill designs tools, not business-agent behavior. When a module should
+also ship a ready business agent through `defineAgent()`, read
+`business-agent-design` and register only the exact tools that agent needs.
+
+## 1. The contract in code
+
+- Composition: `PlatformServerContext` (`modules/auth/src/server/composition.ts`) carries `agentTools: PlatformToolRegistry` (`register(tools)`, `list()`; `packages/kernel/src/tool-registry.ts`; a duplicate tool id throws at boot), `settings: ModuleSettingsRuntime`, and `capabilities: PlatformCapabilityRegistry` (`register(id, service)`, `get(id)`, `has(id)`; `packages/kernel/src/capability-registry.ts`). `platform/octane.config.ts` creates the registries, passes them to every module's `createServerComposition`, declares each `settings`, owns each `dispose`, then calls each `start`.
+- Ordering is a non-issue: `agents.core` (`modules/agents/src/platform.ts`) passes `tools: () => context.agentTools.list()` into `createAgentRuntime`, and the harness is built lazily in `start()`, which runs after every module has composed. Tools any module registers during its own compose are therefore visible, whatever the module order.
+- Helpers: import `defineApiAgentTool` from `@flowdular/sdk/harness/tool-adapters` and the types `AgentTool`, `AgentToolContext` from `@flowdular/sdk/harness/runtime`. Both subpaths are free of the Vercel AI SDK; only the harness root (`@flowdular/sdk/harness`) and `@flowdular/sdk/modules/agents/server` pull it. `defineApiAgentTool` returns a frozen `AgentTool { id, transport: 'api', target, description, requiredPermissions, inputSchema?, execute }`. `defineCliAgentTool({ id, capability: { id, risk }, ... })` wraps a CLI capability and throws at definition time for `external` or `destructive` risk.
+- Skills inside `agents.core` are tenant database records behind `agents.skills.*`, appended to agent instructions. They are unrelated to `.ai/skills/**`, which are files for coding agents.
+- A read tool's output can also become a resolvable `{{ variable }}` for variable-aware fields: the tool's `requiredPermissions` is the variable's scope mask. Register a source on `platformVariableRegistry(context.capabilities)`, require an explicit record binding, and invoke the tool with the trusted tenant, actor permission snapshot, and signal. See the `variables` skill for the complete refusal contract.
+- ADR 0002 (`docs/adr/0002-durable-agent-execution.md`): instructions are data, tools are registered by the composition, each tool records an endpoint id or a CLI capability id plus its required permissions, runs are durable with leases.
+
+## 2. Tool shape
+
+```ts
+// src/agent/tools.ts
+import { defineApiAgentTool } from '@flowdular/sdk/harness/tool-adapters';
+import type { AgentTool } from '@flowdular/sdk/harness/runtime';
+import { PARTY_PERMISSIONS } from '../acl/permissions.ts';
+import type { PartyKind } from '../domain/types.ts';
+import type { PartiesRuntime } from '../server/runtime.ts';
+
+const MAX_TOOL_ROWS = 200;
+
+export function partiesAgentTools(
+	runtime: PartiesRuntime,
+): readonly AgentTool[] {
+	return [
+		defineApiAgentTool({
+			id: 'parties.customer.list', // ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$
+			endpointId: 'parties.records.list', // the read endpoint this wraps
+			description: 'List customers and suppliers of the active tenant.',
+			requiredPermissions: [PARTY_PERMISSIONS.read],
+			inputSchema: {
+				type: 'object',
+				additionalProperties: false,
+				properties: {
+					status: { type: 'string', enum: ['active', 'archived'] },
+					query: { type: 'string', maxLength: 120 },
+				},
+			},
+			execute: async (input, context) => {
+				const value = (input ?? {}) as Record<string, unknown>;
+				const query =
+					typeof value.query === 'string'
+						? value.query.trim().toLocaleLowerCase('en-US')
+						: '';
+				return runtime
+					.service()
+					.list(context.tenantId) // tenant from the run, never from input
+					.filter(
+						(party) =>
+							query === '' ||
+							party.name.toLocaleLowerCase('en-US').includes(query),
+					)
+					.slice(0, MAX_TOOL_ROWS); // bound output
+			},
+		}),
+		defineApiAgentTool({
+			id: 'parties.customer.create',
+			endpointId: 'parties.records.create',
+			description: 'Create a customer or supplier owned by the active tenant.',
+			requiredPermissions: [PARTY_PERMISSIONS.manage],
+			inputSchema: {
+				type: 'object',
+				additionalProperties: false,
+				required: ['name', 'kind'],
+				properties: {
+					name: { type: 'string', maxLength: 160 },
+					kind: { type: 'string', enum: ['customer', 'supplier', 'both'] },
+					vatId: { type: 'string', maxLength: 20 },
+				},
+			},
+			execute: async (input, context) => {
+				const value = (input ?? {}) as Record<string, unknown>;
+				// The service revalidates every field, so a tool cannot persist
+				// what the endpoint would reject.
+				return runtime.service().create(context.tenantId, {
+					name: String(value.name ?? ''),
+					kind: value.kind as PartyKind,
+					vatId: typeof value.vatId === 'string' ? value.vatId : null,
+				});
+			},
+		}),
+	];
+}
+```
+
+```ts
+// src/platform.ts, inside createServerComposition, before the return.
+// register takes readonly unknown[], so no cast is needed.
+context.agentTools.register(partiesAgentTools(runtime));
+```
+
+Export the factory from `src/server/index.ts` so tests and the composition reach it.
+
+Dependencies: `package.json` gets `"@flowdular/sdk/harness": "workspace:*"`. You do not import `@flowdular/sdk/modules/agents` and you do not add `agents.core` to `module.json`: registration flows through the platform-provided registry on the composition context, not an import of agents.core. Adding a scenario bumps `spec/module.yaml` `specVersion` and `module.json` `version` together.
+
+## 3. Execution model you design against (`packages/harness/src/runtime.ts`, `AgentHarness.execute`)
+
+- A tool is offered only when the agent definition lists it in `allowedTools`, the run's explicit `toolGrants` include it, every `requiredPermissions` entry is in the enqueue-time permission ceiling, and the initiating user still holds every permission when the tool is called. The auth runtime reauthorizes the trusted actor and tenant before every call. A stored snapshot never becomes future authority, newly granted scopes do not elevate an old run, and a service actor stays tool-less until its owning module supplies an explicit revocable policy. Otherwise the harness emits `tool.denied` and throws a stable refusal. `assertToolsRegistered` rejects a new run whose agent names an unregistered tool, while an exact idempotent retry returns its already persisted run before consulting mutable definitions or registries.
+- `invokeTool` validates `input` against `inputSchema` first, using a small JSON Schema subset (`type`, `enum`, `required`, `properties`, `additionalProperties: false`, `items`; `packages/harness/src/tool-contract.ts` `validateToolInput`). A violation emits `tool.denied` (reason `TOOL_INPUT_INVALID`) before `execute` runs. The subset does not check string length or format, so the tool enforces those by passing input through the module service.
+- `execute(input, { runId, tenantId, requestedBy, actor, idempotencyKey, permissions, signal })`. Take the tenant from `context.tenantId`. `permissions` is the intersection of the original ceiling and live authorization. `actor` describes the agent run for record history. `additionalProperties: false` already makes the harness refuse a stray `tenantId` field, but never read one anyway.
+- A mutating tool with `idempotency: 'required'` is executable only after the target module implements a durable ledger and the definition declares `idempotencyProtection: 'target-ledger'`. The harness derives a stable key from the durable run id and deterministic tool-call ordinal. The target ledger binds `(tenant, tool id, key)` to a canonical input hash and the first result. A replay returns that result without another mutation; the same key with another tool or input fails closed. Provider tool-call ids are audit metadata only. Never add the declaration before the target migration, repository transaction, and crash-recovery test exist.
+- Each call has a deadline (`tool.timeoutMs`, default 30 s, range 250 to 600000) and the harness caps serialized output at 32 KB (`boundToolOutput`), marking `truncated`. Still page or limit your rows so one call cannot dominate the run window.
+- Events per call land in the run's persisted audit chain: `tool.started`, then `tool.completed` (metadata `tool`, `outputCharacters`, `truncated`) on success, `tool.failed` (reason) on error, or `tool.denied` (reason) when not granted or input-invalid.
+- Runs are enqueued by `POST /api/agent-runs` behind `agents.runs.execute`, claimed by `AgentWorker` with a lease, observed through `GET /api/agent-runs` and the SSE stream. The registered tool ids surface in `GET /api/agents` `tools`, which the Agents form reads to build the allowed-tools grid. Never make a tool block on user input.
+
+## 4. Deliverables for a module
+
+1. Spec: one acceptance scenario per tool group (`PARTIES-AGENT-TOOL`): endpoint wrapped, permission required, validated input, what it refuses (no tenant input; a `manage` tool needs an explicit scenario; bounded output). Bump `specVersion` and `module.json` `version` together.
+2. `src/agent/tools.ts`: every tool calls the module service through the runtime (never a repository, database handle, filesystem or shell), takes `context.tenantId`, and reuses the service validation.
+3. The `register` line in `src/platform.ts`, and the factory exported from `src/server/index.ts`.
+4. For a mutating tool, a numbered migration and target-side idempotency ledger, with the migration mirrored byte for byte in `src/services/migration.ts`. The service commits the business mutation and ledger result in one transaction.
+5. Tests, below, including a replay of the complete harness execution with the same run id and no second business row.
+6. In the Agents screen an agent definition lists the tool id in its allowed tools, the request carries it in `toolGrants`, and the initiating principal still holds the permission. Without all three the tool stays invisible to the model.
+
+## 4b. Worked example
+
+Spec scenario:
+
+```yaml
+acceptanceScenarios:
+  - id: PARTIES-AGENT-TOOL
+    given: An agent run holds parties.records.manage in its permission snapshot and the tool parties.customer.create in its grants.
+    when: The agent invokes the tool with a valid party, and a run without the manage scope invokes the same tool.
+    then: The scoped run creates a tenant-owned party from the run tenant and the harness denies the unscoped run before any write.
+```
+
+Module-local test (`tests/agent-tools.test.ts`) drives `execute` directly. It does
+not assert on `context.permissions`: RBAC is the harness's job, not the tool's.
+
+```ts
+import type { AgentToolContext } from '@flowdular/sdk/harness/runtime';
+import { describe, expect, it } from 'vitest';
+import { partiesAgentTools } from '../src/agent/tools.ts';
+import { createPartiesRuntime } from '../src/server/runtime.ts';
+
+const context = (tenantId: string): AgentToolContext => ({
+	runId: 'run-1',
+	tenantId,
+	requestedBy: 'account-1',
+	permissions: new Set<string>(),
+	signal: new AbortController().signal,
+});
+
+it('creates under the run tenant and ignores a tenant in the input', async () => {
+	const runtime = createPartiesRuntime({ databasePath: ':memory:' });
+	const [, create] = partiesAgentTools(runtime);
+	await create!.execute(
+		{ name: 'Acme', kind: 'customer', tenantId: 'tenant-b' },
+		context('tenant-a'),
+	);
+	expect(runtime.service().list('tenant-a')).toHaveLength(1);
+	expect(runtime.service().list('tenant-b')).toHaveLength(0);
+});
+
+it('reuses the service validation so a tool cannot bypass the endpoint', async () => {
+	const [, create] = partiesAgentTools(
+		createPartiesRuntime({ databasePath: ':memory:' }),
+	);
+	await expect(
+		create!.execute(
+			{ name: 'Acme', kind: 'customer', vatId: 'PL-123' },
+			context('tenant-a'),
+		),
+	).rejects.toMatchObject({ code: 'INVALID_VAT_ID' });
+});
+```
+
+Prove RBAC through the harness (in `modules/agents/tests` with a fake provider,
+where the create tool runs against a `:memory:` repository): a run holding the
+`manage` scope creates the row and emits `tool.started`/`tool.completed`; a run
+whose snapshot lacks it emits `tool.denied` (`TOOL_NOT_GRANTED`) and writes
+nothing.
+
+## 5. Settings a tool may depend on
+
+Declare `settings: defineModuleSettings({...})` (from `@flowdular/sdk/kernel`) by returning it from the composition, keep a reference to `PlatformServerContext.settings` in the tool factory, and read it per call as `settings.get<number>(context.tenantId, '<module>.core', 'key')` at request time, never at boot. Declared settings render in the module's drawer under Administration, Modules automatically.
+
+## Pitfalls
+
+- A tool id equal to an endpoint id is a convention, not a requirement; keep them parallel for traceability. A read-by-id tool with no dedicated endpoint reuses the read endpoint id under the same permission.
+- `requiredPermissions` must be exactly the endpoint's permission; a weaker list lets a run bypass the endpoint's ACL because the tool calls the service directly.
+- Register once per composition; a duplicate id throws in the registry at boot and the platform does not start.
+- Import the helpers from `@flowdular/sdk/harness/tool-adapters` and `@flowdular/sdk/harness/runtime`; never import the harness root or `@flowdular/sdk/modules/agents` from `src/index.ts` or the client, which would pull the Vercel AI SDK into the client bundle.
+- The harness validates only the schema subset; deep validation is the service's job. Pass input through the service so a tool cannot persist what the endpoint would reject.
+- Playground runs use the tenant's readiness-probed provider; the local simulation provider performs no network call and is the only provider in a fresh install.