@flowdular/sdk 0.1.0

package/.ai/references/catalog/tests/support/database.ts

@@ -0,0 +1,76 @@
+import type { DatabaseHandle, DatabaseProvider } from '@flowdular/sdk/database';
+import { createTestDatabaseProvider } from '@flowdular/sdk/database-testing';
+import {
+	DatabaseCatalogRepository,
+	migrateCatalogDatabase,
+} from '../../src/services/database-repository.ts';
+
+const TENANT_TABLES = [
+	'catalog_items',
+	'catalog_items_history',
+	'catalog_items_history_v2',
+	'catalog_idempotency_ledger',
+];
+
+export interface CatalogTestDatabase {
+	readonly provider: DatabaseProvider;
+	readonly runtime: DatabaseHandle;
+	readonly repository: DatabaseCatalogRepository;
+	dispose(): Promise<void>;
+}
+
+/* Booting an embedded PostgreSQL costs about two seconds, so a test file shares
+   one migrated cluster and every fixture starts from truncated tables instead.
+   Call closeCatalogTestDatabases() from the file's afterAll. */
+let shared: Promise<DatabaseProvider> | undefined;
+
+/** The file's migrated provider, with every catalog table emptied. */
+export async function catalogTestProvider(): Promise<DatabaseProvider> {
+	shared ??= (async () => {
+		const provider = createTestDatabaseProvider();
+		const lease = await provider.acquire({
+			namespace: 'catalog.core',
+			purpose: 'migration',
+		});
+		try {
+			await migrateCatalogDatabase(lease.database);
+		} finally {
+			await lease.release();
+		}
+		return provider;
+	})();
+	const provider = await shared;
+	const migration = await provider.acquire({
+		namespace: 'catalog.core',
+		purpose: 'migration',
+	});
+	try {
+		await migration.database.execute({
+			text: `TRUNCATE ${TENANT_TABLES.join(', ')} RESTART IDENTITY CASCADE`,
+		});
+	} finally {
+		await migration.release();
+	}
+	return provider;
+}
+
+/** An empty catalog database with a tenant-scoped runtime handle. */
+export async function createCatalogTestDatabase(): Promise<CatalogTestDatabase> {
+	const provider = await catalogTestProvider();
+	const lease = await provider.acquire({
+		namespace: 'catalog.core',
+		purpose: 'test',
+	});
+	return {
+		provider,
+		runtime: lease.database,
+		repository: new DatabaseCatalogRepository(lease.database),
+		dispose: () => lease.release(),
+	};
+}
+
+export async function closeCatalogTestDatabases(): Promise<void> {
+	const provider = shared;
+	shared = undefined;
+	if (provider) await (await provider).dispose();
+}

package/.ai/references/catalog/translations/en.json

@@ -0,0 +1,101 @@
+{
+	"module.name": "Product Catalog Core",
+	"nav.description": "Products and services",
+	"nav.label": "Catalog",
+	"drawer.subtitle": "Product or service",
+	"drawer.title": "New catalog item",
+	"drawer.editTitle": "Edit catalog item",
+	"action.edit": "Edit",
+	"action.history": "History",
+	"delete.title": "Delete catalog item",
+	"delete.description": "Delete {name} permanently? This cannot be undone.",
+	"delete.drawerDescription": "This permanently removes the archived catalog item.",
+	"delete.confirm": "Delete item",
+	"error.create": "Could not create the catalog item.",
+	"error.update": "Could not update the catalog item.",
+	"error.lifecycle": "Could not change the catalog item lifecycle.",
+	"error.delete": "Could not delete the catalog item.",
+	"error.history": "Could not load catalog item history.",
+	"error.load": "Could not load catalog items.",
+	"error.request": "The catalog operation failed.",
+	"form.cancel": "Cancel",
+	"form.currency": "Currency",
+	"form.kind": "Kind",
+	"form.name": "Name",
+	"form.note": "The SKU is tenant-scoped and cannot change later.",
+	"form.editNote": "SKU is tenant-scoped and cannot change after creation.",
+	"form.price": "Price, minor units",
+	"form.priceHelp": "1000 is 10.00 in the currency below.",
+	"form.sku": "SKU",
+	"form.submit": "Create item",
+	"form.submitting": "Creating…",
+	"form.save": "Save changes",
+	"form.saving": "Saving…",
+	"form.unit": "Unit",
+	"kind.product": "Product",
+	"kind.service": "Service",
+	"status.active": "Active",
+	"status.archived": "Archived",
+	"filters.label": "Filters",
+	"filters.includeArchived": "Include archived items",
+	"lifecycle.title": "Lifecycle",
+	"lifecycle.description": "Archive an item before deleting it permanently.",
+	"lifecycle.history": "View history",
+	"lifecycle.archive": "Archive item",
+	"lifecycle.restore": "Restore item",
+	"lifecycle.delete": "Delete item",
+	"page.action.new": "New item",
+	"page.action.refresh": "Refresh",
+	"page.description": "Products and services with stable tenant-scoped SKUs.",
+	"page.eyebrow": "Commercial master data",
+	"page.title": "Catalog",
+	"price.fallback": "{amount} {currency} minor",
+	"table.caption": "Catalog items",
+	"table.column.item": "Item",
+	"table.column.kind": "Kind",
+	"table.column.price": "Price",
+	"table.column.status": "Status",
+	"table.column.actions": "Actions",
+	"table.count.one": "1 item",
+	"table.count.other": "items: {count}",
+	"table.empty.hint": "Create the first product or service.",
+	"table.empty.title": "No catalog items yet",
+	"table.emptyFiltered.hint": "No item in this workspace matches the current filter.",
+	"table.emptyFiltered.title": "No matching items",
+	"table.loading": "Loading catalog items…",
+	"table.search.label": "Filter catalog items",
+	"table.search.placeholder": "Filter by name or SKU",
+	"table.title": "Products & services",
+	"history.title": "Item history",
+	"history.tableTitle": "Revisions",
+	"history.count": "{count} revisions",
+	"history.caption": "Catalog item revision history",
+	"history.loading": "Loading item history…",
+	"history.emptyTitle": "No revisions yet",
+	"history.emptyHint": "Changes to this item appear here.",
+	"history.emptyValue": "Empty",
+	"history.column.version": "Version",
+	"history.column.action": "Action",
+	"history.column.actor": "Actor",
+	"history.column.changes": "Changes",
+	"history.column.date": "Date",
+	"history.action.created": "Created",
+	"history.action.updated": "Updated",
+	"history.action.archived": "Archived",
+	"history.action.restored": "Restored",
+	"history.action.deleted": "Deleted",
+	"history.actor.user": "User",
+	"history.actor.agent": "Agent",
+	"history.actor.service": "Service",
+	"history.actor.serviceConfiguredBy": "Service, configured by {name}",
+	"history.field.sku": "SKU",
+	"history.field.name": "Name",
+	"history.field.kind": "Kind",
+	"history.field.unit": "Unit",
+	"history.field.basePriceMinor": "Price",
+	"history.field.currency": "Currency",
+	"history.field.status": "Status",
+	"widget.label": "Catalog items",
+	"widget.link": "Open catalog",
+	"widget.note": "Active catalog entries with tenant-scoped SKUs."
+}

package/.ai/references/catalog/translations/pl.json

@@ -0,0 +1,101 @@
+{
+	"module.name": "Katalog produktów i usług",
+	"nav.description": "Produkty i usługi",
+	"nav.label": "Katalog",
+	"drawer.subtitle": "Produkt lub usługa",
+	"drawer.title": "Nowa pozycja katalogu",
+	"drawer.editTitle": "Edytuj pozycję katalogu",
+	"action.edit": "Edytuj",
+	"action.history": "Historia",
+	"delete.title": "Usuń pozycję katalogu",
+	"delete.description": "Usunąć trwale pozycję {name}? Tej operacji nie można cofnąć.",
+	"delete.drawerDescription": "Ta operacja trwale usuwa zarchiwizowaną pozycję katalogu.",
+	"delete.confirm": "Usuń pozycję",
+	"error.create": "Nie udało się utworzyć pozycji katalogu.",
+	"error.update": "Nie udało się zaktualizować pozycji katalogu.",
+	"error.lifecycle": "Nie udało się zmienić cyklu życia pozycji katalogu.",
+	"error.delete": "Nie udało się usunąć pozycji katalogu.",
+	"error.history": "Nie udało się wczytać historii pozycji katalogu.",
+	"error.load": "Nie udało się wczytać pozycji katalogu.",
+	"error.request": "Operacja na katalogu nie powiodła się.",
+	"form.cancel": "Anuluj",
+	"form.currency": "Waluta",
+	"form.kind": "Rodzaj",
+	"form.name": "Nazwa",
+	"form.note": "SKU obowiązuje w tej przestrzeni roboczej i później nie da się go zmienić.",
+	"form.editNote": "SKU obowiązuje w tej przestrzeni roboczej i nie można go zmienić po utworzeniu.",
+	"form.price": "Cena w groszach",
+	"form.priceHelp": "1000 to 10,00 w wybranej niżej walucie.",
+	"form.sku": "SKU",
+	"form.submit": "Utwórz pozycję",
+	"form.submitting": "Tworzenie…",
+	"form.save": "Zapisz zmiany",
+	"form.saving": "Zapisywanie…",
+	"form.unit": "Jednostka",
+	"kind.product": "Produkt",
+	"kind.service": "Usługa",
+	"status.active": "Aktywna",
+	"status.archived": "Zarchiwizowana",
+	"filters.label": "Filtry",
+	"filters.includeArchived": "Pokaż zarchiwizowane pozycje",
+	"lifecycle.title": "Cykl życia",
+	"lifecycle.description": "Zarchiwizuj pozycję przed jej trwałym usunięciem.",
+	"lifecycle.history": "Zobacz historię",
+	"lifecycle.archive": "Archiwizuj pozycję",
+	"lifecycle.restore": "Przywróć pozycję",
+	"lifecycle.delete": "Usuń pozycję",
+	"page.action.new": "Nowa pozycja",
+	"page.action.refresh": "Odśwież",
+	"page.description": "Produkty i usługi ze stałym SKU w obrębie przestrzeni roboczej.",
+	"page.eyebrow": "Dane podstawowe sprzedaży",
+	"page.title": "Katalog",
+	"price.fallback": "{amount} {currency} w groszach",
+	"table.caption": "Pozycje katalogu",
+	"table.column.item": "Pozycja",
+	"table.column.kind": "Rodzaj",
+	"table.column.price": "Cena",
+	"table.column.status": "Status",
+	"table.column.actions": "Akcje",
+	"table.count.one": "1 pozycja",
+	"table.count.other": "pozycje: {count}",
+	"table.empty.hint": "Dodaj pierwszy produkt lub usługę.",
+	"table.empty.title": "Nie ma jeszcze pozycji katalogu",
+	"table.emptyFiltered.hint": "Żadna pozycja w tej przestrzeni roboczej nie pasuje do filtra.",
+	"table.emptyFiltered.title": "Brak pasujących pozycji",
+	"table.loading": "Wczytywanie pozycji katalogu…",
+	"table.search.label": "Filtruj pozycje katalogu",
+	"table.search.placeholder": "Filtruj po nazwie lub SKU",
+	"table.title": "Produkty i usługi",
+	"history.title": "Historia pozycji",
+	"history.tableTitle": "Wersje",
+	"history.count": "Liczba wersji: {count}",
+	"history.caption": "Historia zmian pozycji katalogu",
+	"history.loading": "Wczytywanie historii pozycji…",
+	"history.emptyTitle": "Brak wersji",
+	"history.emptyHint": "Zmiany tej pozycji pojawią się tutaj.",
+	"history.emptyValue": "Puste",
+	"history.column.version": "Wersja",
+	"history.column.action": "Akcja",
+	"history.column.actor": "Aktor",
+	"history.column.changes": "Zmiany",
+	"history.column.date": "Data",
+	"history.action.created": "Utworzono",
+	"history.action.updated": "Zmieniono",
+	"history.action.archived": "Zarchiwizowano",
+	"history.action.restored": "Przywrócono",
+	"history.action.deleted": "Usunięto",
+	"history.actor.user": "Użytkownik",
+	"history.actor.agent": "Agent",
+	"history.actor.service": "Usługa",
+	"history.actor.serviceConfiguredBy": "Usługa skonfigurowana przez: {name}",
+	"history.field.sku": "SKU",
+	"history.field.name": "Nazwa",
+	"history.field.kind": "Rodzaj",
+	"history.field.unit": "Jednostka",
+	"history.field.basePriceMinor": "Cena",
+	"history.field.currency": "Waluta",
+	"history.field.status": "Status",
+	"widget.label": "Pozycje katalogu",
+	"widget.link": "Otwórz katalog",
+	"widget.note": "Aktywne pozycje katalogu z SKU w obrębie przestrzeni roboczej."
+}

package/.ai/references/catalog/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"allowImportingTsExtensions": true,
+		"isolatedModules": true,
+		"jsx": "react-jsx",
+		"jsxImportSource": "octane",
+		"types": ["node"],
+		"plugins": [{ "name": "@tsrx/typescript-plugin" }]
+	},
+	"include": ["src/**/*", "tests/**/*.ts"]
+}

package/.ai/references/catalog/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config';
+
+/* Booting the embedded PostgreSQL a suite runs against takes seconds under
+   parallel load, well past the 5s vitest default.
+
+   Deliberately self-contained. A sandbox session copies this module into its
+   own workspace and runs these gates there, so importing a shared preset from
+   another workspace package would leave vitest unable to load its config in
+   that copy. The duplication is the price of that isolation; keep it. */
+export default defineConfig({
+	test: {
+		maxWorkers: 2,
+		testTimeout: 30_000,
+		hookTimeout: 30_000,
+	},
+});

package/.ai/references/catalog.provenance.json

@@ -0,0 +1,55 @@
+{
+	"id": "catalog.core",
+	"version": "0.6.1",
+	"repository": "Flowdular/official-modules",
+	"sourceCommit": "8ed1e780ba7405d0bdf5082882b92d130b72d081",
+	"artifactSha256": "9010086822aa5f4d13176e465022fd2118c5dd0cb157200b31c2940fec1f3513",
+	"files": {
+		"LICENSE": "155d722071bad9d0d832482e06fd5a47f7034389cb63aabcb39f4282aa3499fc",
+		"migrations/0001_catalog_core.down.sql": "0962a1edf0bde959cd4facccf77bd5b634d6cc25f125a0c79a61770c8871093f",
+		"migrations/0001_catalog_core.up.sql": "602ed9c1852b729cf278cf8536f79e3f7432f23a5a60c50d8826f5c1b9442d18",
+		"migrations/0002_catalog_history.down.sql": "7f163e11ca9033101e3bb1de61481b1a8043c204e65aa2bb508a13b065e98c78",
+		"migrations/0002_catalog_history.up.sql": "3aa30993b1676cf357c2ef87f19a7d4b64b77041c0e4bc743fced04521471c28",
+		"migrations/0003_catalog_history_service_actors.down.sql": "f20ecc8d7d753af3d2b6fdbff9d637fd938884cfbd88b08a30958e6aa000132b",
+		"migrations/0003_catalog_history_service_actors.up.sql": "7caae787ca2fc1e331ccbfda4df5982beec76136e8dc486aab5532ccd338a722",
+		"migrations/0004_catalog_idempotency_ledger.down.sql": "8ba72d8edc4d25ecf6d041888cf321690c25afdaf3723812ddd7d391d75370aa",
+		"migrations/0004_catalog_idempotency_ledger.up.sql": "41e86ba2051159c6cc9672bfae17c1d02051da975f1c43c566a2b66592673cb0",
+		"migrations/README.md": "2a15fd001713c2552a3c82b186246aa5fec136f43143cc2d9aa15bd491a09d41",
+		"module.json": "66afd7635404b565e8b86f7c5bc485c85c9d568144858bfcff8a4a9429f76081",
+		"package.json": "08b76b72f6fd7a8e3b08113c135899f6010b5fbbea8ca6be0b68b599afe75dad",
+		"spec/module.yaml": "2df3b7c2cbd20f5f5950b469b092f85ef140875bf789a69da04fb6dc68ae0ff8",
+		"src/acl/permissions.ts": "3375521a5a229736ffac5a948140ec347dc7a7e4fba80e778c0baaf9e0622590",
+		"src/agent/tools.ts": "3204d20886d2b864482adc1ed3303c653aebd207e16c4fce0c67a4979ea8db07",
+		"src/api/endpoints.ts": "34f1036e759353550be2acf67c6fa254afc790942d09489db2e76a082df5c3a3",
+		"src/client/CatalogHistoryDrawer.tsrx": "6cdba5249be81e70da703cb34c1a2210943ce5e5fb596ee77cf7952e2acf3ee3",
+		"src/client/CatalogItemForm.tsrx": "7dafa4149975d9e7d5784c8a5391b5b64c2405991aaead713d94b61c41168c2c",
+		"src/client/CatalogView.tsrx": "7c507931f33afea8414b002e3ad815740c8db75016c53d8a81effc6427bd958d",
+		"src/client/api.ts": "5f404f6b25777bc8fe2eab5a35424593abc8e879fb83fa2ae4d637fc23fdce4b",
+		"src/client/contribution.tsrx": "e95f755882005ee090c99a119ce2dda2ec70420daed4ce06021193905858c62f",
+		"src/client/index.ts": "03eb0664cdafccb66cb25f2e1b07e6959c2dfa9bdbfffc3e7edf9b535ba4949a",
+		"src/client/navigation-copy.ts": "9a8757e64f4001a93e2bc2861c686a19f791f9d67a396d9e658023b1ec4cea8f",
+		"src/client/state.ts": "bc054bc269026b6abf60d99a2fc5dd94eb8a488fc1ce4c81a1ae1065d9db576b",
+		"src/domain/types.ts": "4b26be80954d792b09a3a34d29d845b9f6119640be505daba325fec820e06ef6",
+		"src/domain/variables.ts": "131130e57838235b1f3fcb799da44baeae16522bb346d522827e022305c110b5",
+		"src/index.ts": "5b27943018db9a18651d62add7d6f8397d7c492a204381fae74547b99b91990d",
+		"src/platform.ts": "3bdc15a5749cceeca4e86388fad13aebcbc151bb4226852d46ed7845248c4efe",
+		"src/server/index.ts": "90eae107d863418124e5d10c4d1fe8a119bd14da605b36de708c18d8500c4b5e",
+		"src/server/runtime.ts": "5f4389a6adf8265f6737c489baf686f63cc3550662103d28b2da9800dd9f5b63",
+		"src/services/catalog-service.ts": "e5ffa703f6a87e4e2e762f5beb87952be40b3b5847d10b373033a9b01fa4a378",
+		"src/services/database-repository.ts": "b513a9459fb3fc1362e9dcd98c10a104b02dbb748ae23c59c6768c2f0e7a1466",
+		"src/services/index.ts": "a08aefe5101814538666f861536287fc382e6c655d62ba9b9ef4bbfbc6ede4af",
+		"src/services/migration.ts": "89c8e333482c80bc819deba0cf4f4e37e94137933af0f6503f4f9ebcb4f5f371",
+		"src/services/repository.ts": "df0f1364cb05031972993c873faf6bcb7fbe4c92d05a04ae980497d9a732dd7f",
+		"src/services/target-idempotency.ts": "7111b56a30b691eaaaa64f5691895ac94b6e0735b0079794835bbbeba5102cb0",
+		"tests/agent-tools.test.ts": "3cdda30b5454d58c6e8791a98e3daf6fe58b9852cd5c437b3614c3f6123baa91",
+		"tests/endpoints.test.ts": "24d05c7dd52820f90c777a1b814529f5188a9a5a9daeaacda07314f17b7483cc",
+		"tests/idempotency.test.ts": "f2e0896635bcd95271b66181daa2c084411913cdf864ae8b4814f2beeb8c2943",
+		"tests/migrations.test.ts": "47d3d741eddde8677be287730d2f96af556b4b7bf0d8378f9a12a7309af17d78",
+		"tests/module.test.ts": "01bedfa1540470cc87c808c75120f6ede7c3b8e3d81e340d2076af0a66f1c7ab",
+		"tests/support/database.ts": "f108cf6390da7669f8935301fac125a7e5653f06ba75327f4bdc28fdd409ba73",
+		"translations/en.json": "406a40b77e3778e83cd4d30e7b3aee8f89c75baf7bc52f1befc6d16f3b877ab3",
+		"translations/pl.json": "db6325b4980d978e1a3098758b5259a68e32469baa09d194b9d6746462776d27",
+		"tsconfig.json": "140bb4775df421146563d13d2f78ff74cb3c2decab6737db32938339248a92ba",
+		"vitest.config.ts": "d13725b13c3712ec91c1646e9226fb172eec2599f72f4e6608bece9912e2bd81"
+	}
+}

package/.ai/skills/README.md

@@ -0,0 +1,36 @@
+# Skills
+
+Flowdular is an agentic foundation framework: the platform is the foundation, and these skills are how a coding agent (a sandbox specialist or your own tool) builds on it correctly. Each `SKILL.md` is a procedure plus pitfalls, verified against the code it cites, with front matter `name` (equals the directory), `description`, `roles` (who reads it) and `when` (one line).
+
+| Skill                   | One line                                                                                                              |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `module-new`            | Create a module from an approved spec: scaffold, what the scaffold lacks, server and client file sets, enable, grant. |
+| `module-update`         | Change an existing module with a fixed touch list per change class and the version bump rules.                        |
+| `spec-approval`         | Record explicit user approval of an exact current module spec without letting an agent approve its own work.          |
+| `auto-review`           | Review finished changes against requirements, contracts and regression evidence before delivery.                      |
+| `core-extend`           | Change a platform package without breaking modules, generated files, or the copies sandbox sessions read.             |
+| `bug-hunt`              | Reproduce with the gate runner, map the symptom to its layer, fix there with a failing test, hunt siblings.           |
+| `perf-audit`            | Hot paths of server, client, bundle and agent runtime; measure before changing anything.                              |
+| `ux-design`             | The record-screen recipe, five states, component and class inventory, icon keys, copy rules.                          |
+| `auth-security-review`  | Endpoint threat surface, scope model, API tokens, secrets, greps, destructive CLI rules, required tests.              |
+| `test-hardening`        | Where tests run, the route recipe, the embedded PostgreSQL provider, required cases, break-the-implementation check.  |
+| `migration-authoring`   | Numbered SQL, byte-identical constants, the checksum ledger, safe adoption, and immutable applied migrations.         |
+| `database-adapter`      | Build a repository on the async provider contract: PostgreSQL SQL, provider leases, forced RLS, isolation tests.      |
+| `translations-i18n`     | Live module bundles, fully qualified keys, locale-aware formatting, parity checks, and raw-key diagnosis.             |
+| `cli-extension`         | Module CLI commands through `commands.json` and `defineCliExtension`, with the runner's approval rules.               |
+| `agent-tool-design`     | Register module tools through the live composition registry with tenant, permission, input, output, and audit bounds. |
+| `business-agent-design` | Ship a module-owned business agent with an exact tool ceiling, tenant binding, revisions, and access tests.           |
+| `variables`             | Variable-aware fields and templates: the `{{ }}` contract, the scope mask, server-side resolution, adding a source.   |
+| `workflow-development`  | Build, publish, invoke, simulate, and test typed durable workflows and their module integration capability.           |
+| `release-eject-pr`      | Sandbox eject sequence, repository gates, branch and PR conventions, post-merge scope grant.                          |
+
+Choose one skill per task phase: the most specific matching entry above. For ordinary module work use `module-new` or `module-update`. Finish the phase before switching; do not recursively load other SKILL.md files mentioned in a skill. Consult relevant code and supporting references only as needed. `spec-approval` is host-only and requires an explicit user approval instruction.
+
+Where they are read:
+
+- Sandbox: copies are available in `reference/skills/`, but each turn receives exactly one Task skill selected by role, blueprint and request. An explicit `$skill-name` takes precedence only if installed and eligible for that role. Missing matches never load the whole catalog.
+- Claude Code: RuleSync generates `.claude/skills` from this directory.
+- Codex: RuleSync generates `.agents/skills` from this directory.
+- Other tools: use the canonical skill here or add another RuleSync target in `rulesync.jsonc`.
+
+Adding a skill: create `.ai/skills/<kebab-name>/SKILL.md` with the four front matter keys, keep the instructions focused, cite the owning code, add a row above and update the sandbox routing when applicable. Run `pnpm rules:generate` after formatting. `pnpm rules:check` verifies every generated copy.

package/.ai/skills/agent-tool-design/SKILL.md

@@ -0,0 +1,209 @@
+---
+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.
+roles:
+  - agentic-engineer
+  - backend-engineer
+  - module-executor
+when: A brief asks to expose a module operation as a tool to business agents or workflows.
+---
+
+# 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.