@flowdular/sdk 0.1.0

package/modules/agents/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@flowdular/module-agents",
+	"version": "0.9.1",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./client": "./src/client/index.ts",
+		"./server": "./src/server/index.ts",
+		"./platform": "./src/platform.ts",
+		"./module.json": "./module.json"
+	},
+	"scripts": {
+		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@flowdular/cli-protocol": "workspace:*",
+		"@flowdular/client": "workspace:*",
+		"@flowdular/contracts": "workspace:*",
+		"@flowdular/database": "workspace:*",
+		"@flowdular/harness": "workspace:*",
+		"@flowdular/kernel": "workspace:*",
+		"@flowdular/module-auth": "workspace:*",
+		"@flowdular/server": "workspace:*",
+		"@flowdular/ui": "workspace:*",
+		"octane": "0.1.51",
+		"segment-state": "0.2.0"
+	},
+	"devDependencies": {
+		"@flowdular/database-testing": "workspace:*",
+		"@tsrx/typescript-plugin": "0.3.120",
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.10"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/flowdular.git",
+		"directory": "modules/agents"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"private": true
+}

package/modules/agents/spec/module.yaml

@@ -0,0 +1,271 @@
+schemaVersion: 1
+id: agents.core
+specVersion: 0.9.1
+status: approved
+name: Agentic Core
+description: Provides tenant-created and module-owned business agent definitions, tenant-scoped provider connections, reusable procedures, durable streamed execution, run history, and the public run queue used by optional automation modules.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+  - integration
+  - cli
+dependencies:
+  - id: system.core
+    range: 0.5.0
+  - id: auth.core
+    range: 0.10.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Every agent managed by agents.core is a business agent with explicit ownership. A tenant-created definition is owned by one tenant; a module-owned definition is owned by one enabled module and receives a separate tenant-scoped execution binding. Sandbox coding specialists are outside agents.core. Every binding, run, and repository query receives the trusted tenant identifier.
+  - An enabled module may register immutable business agent behavior during platform composition with defineAgent. Its stable identity is derived from module id and agent key, its positive definition revision is supplied by the module, and malformed or duplicate identities fail platform boot before workers start.
+  - Module-owned instructions, names, maximum tool allowlists, and execution limits are read-only module source. A tenant administrator may bind an available provider and model, pause the binding, and reduce its enabled tool set, but cannot broaden the module allowlist or edit the module behavior in the Agents UI.
+  - An unconfigured module-owned agent is visible as unconfigured but cannot be activated, published in a workflow, or executed until its tenant binding names a usable provider and model.
+  - A module definition revision is content-stable. Reusing one revision with different executable content or moving backwards fails platform boot. A higher definition revision creates a new immutable tenant executable revision for every existing binding without changing retained revisions.
+  - Tenant-created and module-owned executable revisions share one exact-revision contract. A provider, model, module definition revision, instructions, limits, and effective maximum tools are retained before the revision can be used by a workflow.
+  - Agent execution is durable and fire-and-forget. The enqueue request persists a queued run before returning and never waits for provider completion.
+  - Queued and interrupted runs are recovered after runtime restart without executing one run concurrently more than once inside a process.
+  - Browser lifecycle and authenticated session lifetime do not control a queued run after the enqueue transaction commits.
+  - Workers claim runs with expiring leases so an interrupted claim can be recovered without allowing two live workers to own the same run.
+  - Every claimed run receives a short-lived signed run grant bound to tenant, run, provider, model, worker, attempt, permission digest, tool-grant digest, and current lease. The provider broker atomically consumes the grant once and never returns the upstream credential.
+  - Run grants are stored only as hashes and safe identifiers. A replay, expired grant, wrong audience, invalid signature, or grant presented after lease loss is rejected before provider resolution.
+  - A single claimed execution can remain detached for up to 24 hours while the worker renews its lease. Provider calls and tools must still use narrower operation timeouts and idempotency controls where side effects are possible.
+  - Agent instructions never grant authority. Model execution can reach platform behavior only through registered agent tools and never receives the platform capability registry directly.
+  - Agent instructions are a variable template. The stored definition keeps the raw double-brace template; every run snapshot carries the instructions resolved against the run context (tenant name, principal, UTC date) before the harness executes. A variable is offered and resolved only when the principal holds the scope declared by its source.
+  - Arbitrary source code, shell commands, raw secrets, and runtime-downloaded client code cannot be stored as agent configuration.
+  - Provider, model, instruction revision, limits, input, output, usage, and execution events are captured with every run.
+  - Authorization decisions use server-side RBAC scopes and persist the initiating subject plus a permission snapshot for audit without treating that snapshot as future authority.
+  - Playground runs use the same authorization, tenancy, budgets, provider adapter, and audit path as platform-triggered runs.
+  - The bundled local simulation provider has network access disabled and does not claim to be a production language model.
+  - Agent definitions, playground, run history, providers, procedures, and usage are contributed under one collapsible Agents navigation group owned by agents.core. The product never presents these business procedures as coding-agent skills, and the `.ai/skills` and `.agents/skills` authoring catalogs remain separate concepts.
+  - Provider connections are configured through authenticated agents.core APIs and stored as tenant-owned metadata plus an encrypted credential envelope; raw credentials never enter client responses, logs, audit metadata, agent definitions, run snapshots, or harness events.
+  - The credential encryption key is external to the agents database. Production startup fails when no explicit key is configured, while local development may create a permission-restricted key file outside the database.
+  - Provider credentials are decrypted just in time for one claimed execution or readiness probe and are not retained by the harness after that operation.
+  - Provider adapters use the Vercel AI SDK language model contract. Bundled adapter kinds are Vercel AI Gateway, Azure OpenAI, OpenAI, OpenAI-compatible, Anthropic, and local simulation.
+  - An OpenAI-compatible base URL must use HTTPS and match a deployment-controlled outbound hostname allowlist; provider configuration cannot create arbitrary network access or target private infrastructure.
+  - A readiness probe performs a bounded server-side model request, records only safe status, latency, model, and error classification, and never returns provider response bodies or credentials.
+  - An agent can be activated only when its provider connection is enabled, its selected model is enabled, and the latest readiness result is healthy within the configured freshness window.
+  - Procedures are versioned instruction and capability bundles. A procedure cannot contain executable source code, credentials, or grant a tool that is not independently registered and authorized.
+  - Procedures are canonical in the domain model and authenticated API through procedureIds, procedureSnapshots, a procedures response collection, and `/api/agent-procedures` mutation routes. Deprecated skill-named fields and `/api/agent-skills` routes operate on the same records and revisions during the compatibility window and never create a second resource.
+  - Existing authorization grants, database rows, run evidence, and audit chains survive the product rename without rewriting history. The stable `agents.skills.read` and `agents.skills.manage` permission identifiers, legacy `agent_skills` storage names, and historical `agent-skill` audit identifiers remain compatibility details while their user-facing labels and descriptions say procedures.
+  - Archiving an agent prevents new runs while keeping durable run evidence. Deletion requires an archived, unreferenced record and never cascades through run history or active agent assignments.
+  - Tool calls use validated input schemas, explicit grants, target-module server authorization, timeouts, output limits, and persisted start, completion, or denial events. A run sees only the exact intersection of the definition allowlist, a module binding reduction when present, the invocation grants, and tools whose required permissions exist in the initiating actor's trusted permission snapshot. Wildcards never grant tools.
+  - Web search is disabled by default and requires an explicit agent policy plus a registered web search capability. Provider-native web search cannot bypass the same permission, budget, audit, and egress controls.
+  - Worker output is streamed into ordered durable run events. UI streaming observes persisted events and never owns or cancels the underlying run lifecycle.
+  - Workflow, service, and optional automation modules use the same durable enqueue capability as the playground and include a stable idempotency key and initiating principal or approved system principal.
+  - agents.core does not own automation schedules, webhook definitions, trigger secrets, or an automation clock. Optional modules reach it only through the public agents.run-queue capability.
+  - A run's cost is computed once, from its reported usage and a published per-model price, in the same transaction that settles the run. A model without a published price is recorded in tokens and left unpriced, never priced at a guess.
+  - Budget caps are tenant-scoped module settings checked when a run is enqueued. A run already executing is never stopped mid-way, so concurrent enqueues may overshoot a cap by the cost of the runs still in flight.
+  - Every saved agent revision is retained as an immutable executable snapshot, including its ownership, exact instructions, procedures, tools, provider, model, and limits.
+  - Workflow agent nodes request an exact retained revision through agents.run-execution.v2. The request is workflow-bound, tenant-bound, idempotent, observable through persisted events, and cancellable through the same capability.
+  - A structured-output run starts only when its pinned provider can guarantee the declared JSON Schema contract. The harness validates the returned JSON again before the worker settles the run.
+  - Business actions exposed to workflows are explicit versioned contracts. Only read and workspace-write risks are eligible, input and output are schema checked, and every invocation is persisted before execution.
+  - Workflow action invocations receive a trusted actor, permission snapshot, idempotency key, and AbortSignal. Secrets, raw input, and raw output never enter audit metadata.
+  - Every request-time read and write runs on a tenant-scoped database handle. The worker recovery polls are the only cross-tenant reads, they run on a separate read-only role, and the module agent catalog is reconciled at boot on the schema-owner lease that runs migrations.
+  - Every table that carries tenant data enables and forces row-level security with a policy bound to the transaction-local tenant, including the child tables that hang off a run, a definition or a provider connection. A read by a caller-supplied parent id therefore cannot cross a workspace even when application code forgets the predicate.
+permissions:
+  - id: agents.definitions.read
+    description: Read agent definitions in the active tenant.
+  - id: agents.definitions.manage
+    description: Create and update agent definitions in the active tenant.
+  - id: agents.runs.read
+    description: Read agent runs and execution traces in the active tenant.
+  - id: agents.runs.execute
+    description: Queue playground and platform agent runs in the active tenant.
+  - id: agents.providers.read
+    description: Read safe provider connection metadata and readiness in the active tenant.
+  - id: agents.providers.manage
+    description: Create, rotate, enable, disable, and remove provider connections in the active tenant.
+  - id: agents.providers.test
+    description: Execute a bounded readiness probe against a configured provider model.
+  - id: agents.skills.read
+    description: Read reusable agent procedures in the active tenant. The skill-named identifier is retained for authorization compatibility.
+  - id: agents.skills.manage
+    description: Create and version reusable agent procedures in the active tenant. The skill-named identifier is retained for authorization compatibility.
+dataOwnership:
+  - Business modules own the current module-supplied definition and semantic revision of each module-owned business agent they register.
+  - agents.core owns tenant-created agent identity and configuration, tenant bindings for module-owned agents, provider and model selection, reduced tool grants, executable revisions, and lifecycle status.
+  - agents.core owns durable run state, input and output snapshots, usage, timing, failure data, and append-only execution events.
+  - agents.core owns provider connection metadata, encrypted credential envelopes, configured model allowlists, readiness history, and credential revision identifiers.
+  - agents.core owns procedure identity, versioned instructions, required tool identifiers, lifecycle status, and agent-to-procedure assignments. Existing skill-named storage objects hold the same procedure records during the compatibility window.
+  - agents.core owns the per-run cost projection, its per-day and per-agent rollups, and the budget caps declared as module settings.
+  - agents.core owns immutable agent revision snapshots, workflow-bound run output contracts, and durable versioned action invocation state.
+  - Business modules own their records and expose narrowly scoped tools to the harness; agents.core never bypasses their services or ACL rules.
+acceptanceScenarios:
+  - id: AGENTS-LIST
+    given: Tenant-created business agents and enabled modules with module-owned business agents exist.
+    when: An authorized principal lists agents.
+    then: The active tenant receives a deterministic catalog with an explicit tenant or module ownership discriminator and no definition from another tenant or disabled module.
+  - id: AGENTS-MODULE-REGISTER
+    given: An enabled module registers a valid defineAgent definition during composition.
+    when: The platform finishes composing modules before starting workers.
+    then: The agent registry seals a frozen definition with a stable module-derived identity, while a malformed definition, duplicate identity, wildcard tool, or conflicting same-revision content fails boot.
+  - id: AGENTS-MODULE-BIND
+    given: A module-owned agent is registered but has no tenant execution binding.
+    when: A tenant manager selects a healthy provider and model, chooses a subset of the code allowlist, and activates the binding.
+    then: agents.core creates a tenant-scoped immutable executable revision and the business agent becomes runnable without copying or editing its module-owned behavior.
+  - id: AGENTS-MODULE-READONLY
+    given: A principal can manage agent definitions in the active tenant.
+    when: The principal opens, updates, archives, or deletes a module-owned agent.
+    then: The UI and API allow only binding changes such as provider, model, paused state, and tool reduction, and refuse edits or deletion of the module-owned definition with a stable error.
+  - id: AGENTS-MODULE-REVISION
+    given: Existing tenant bindings point at a retained executable revision of a module-owned agent.
+    when: A deployment registers a higher module definition revision.
+    then: Existing bindings advance to a new immutable executable revision, old workflow references retain their exact snapshot, and a code downgrade or same-revision content drift fails boot.
+  - id: AGENTS-MODULE-UNAVAILABLE
+    given: A workflow or caller references a module-owned agent whose owning module is no longer registered.
+    when: It lists current agents or requests a new execution.
+    then: The agent is unavailable for new work and the request is refused without deleting retained revisions, completed runs, or audit evidence.
+  - id: AGENTS-CREATE
+    given: An authorized principal supplies valid instructions, provider, model, limits, and tool grants.
+    when: The agent is created.
+    then: A tenant-owned draft agent is persisted at revision one without storing credentials or executable source code.
+  - id: AGENTS-UPDATE
+    given: An authorized principal edits an agent owned by the active tenant.
+    when: The update is accepted.
+    then: The definition revision increments and future runs snapshot the new revision while historical runs remain unchanged.
+  - id: AGENTS-QUEUE
+    given: An active agent and a principal with execution permission.
+    when: A playground or platform run is requested.
+    then: A queued run is durably persisted and a 202 response is returned before provider execution completes.
+  - id: AGENTS-EXECUTE
+    given: A queued run with valid server-side grants and bounded execution settings.
+    when: The harness worker claims the run.
+    then: The run reaches succeeded or failed with output, usage, timestamps, and ordered execution events persisted.
+  - id: AGENTS-RECOVER
+    given: The process stops after a run was queued or claimed.
+    when: The runtime starts again.
+    then: Pending runs are recovered and scheduled without duplicate concurrent execution inside that runtime.
+  - id: AGENTS-DETACHED
+    given: A run was durably queued by an authorized principal.
+    when: The initiating browser disconnects or its session later expires.
+    then: The worker continues the run from persisted state using bounded execution grants captured by the server at enqueue time.
+  - id: AGENTS-AUDIT
+    given: An agent is created, changed, queued, claimed, completed, or failed.
+    when: The state transition commits.
+    then: An append-only tenant-scoped audit event records the actor, action, subject, timestamp, and safe metadata without raw credentials.
+  - id: AGENTS-PLAYGROUND
+    given: An authorized user enters test input for an active agent.
+    when: The playground queues the run.
+    then: The UI returns immediately, polls the durable run, and renders its final output or stable failure without a blocking request.
+  - id: AGENTS-DENY
+    given: A principal is unauthenticated, lacks the required scope, or targets another tenant.
+    when: The principal reads, configures, or executes an agent.
+    then: The server denies the operation before cross-tenant data or provider execution is exposed.
+  - id: AGENTS-PROVIDER-CREATE
+    given: An owner with provider management permission submits a supported provider kind, safe metadata, model allowlist, and credential.
+    when: The provider connection is created.
+    then: Tenant-owned metadata and an encrypted credential envelope are persisted while the response exposes only credential presence and revision.
+  - id: AGENTS-PROVIDER-ROTATE
+    given: An existing provider connection and a new credential.
+    when: An authorized owner rotates the credential.
+    then: The encrypted envelope and credential revision change, existing run history stays immutable, and no raw credential is logged or returned.
+  - id: AGENTS-PROVIDER-READINESS
+    given: An enabled provider connection, an enabled model, and a principal with provider test permission.
+    when: A readiness probe is requested.
+    then: A bounded Vercel AI SDK request verifies authentication and model execution and stores safe health, latency, timestamp, and error classification.
+  - id: AGENTS-PROVIDER-SSRF-DENY
+    given: An OpenAI-compatible connection targets a non-HTTPS, private, loopback, link-local, or non-allowlisted hostname.
+    when: Configuration or a readiness probe is attempted.
+    then: The operation is denied before any outbound request or credential use.
+  - id: AGENTS-PROVIDER-ACTIVATION
+    given: An agent references an unknown, disabled, stale, or unhealthy provider model.
+    when: Activation or enqueue is requested.
+    then: The server rejects the operation with a stable readiness error and no provider call starts.
+  - id: AGENTS-PROCEDURE
+    given: An authorized owner defines a procedure with bounded instructions and registered required tools.
+    when: The procedure is attached to an agent and the agent runs.
+    then: The harness receives the approved procedure revision, merges its instructions, intersects its tools with agent and run grants, and persists evidence of each capability invoked.
+  - id: AGENTS-PROCEDURE-COMPATIBILITY
+    given: Existing clients, permission grants, databases, retained revisions, and audit events use the former skill-named contract.
+    when: agents.core is upgraded to the procedure-named contract.
+    then: The canonical and deprecated API surfaces resolve the same tenant-owned procedure ids and revisions, existing data remains readable and writable without copying it, and no authorization grant, run snapshot, or audit-chain hash is rewritten.
+  - id: AGENTS-PROCEDURE-NAVIGATION
+    given: A principal can read reusable agent procedures.
+    when: The principal opens the Agents navigation or follows the former agent-skills deep link.
+    then: The product shows one Procedures screen with procedure terminology throughout, while the former deep link resolves to that same screen without adding a duplicate navigation item.
+  - id: AGENTS-TOOL-BOUNDARY
+    given: An agent definition has an exact tool allowlist, a module binding may reduce it, an invocation requests explicit grants, and the actor carries a trusted permission snapshot.
+    when: The run is enqueued and the model requests tools.
+    then: The persisted and exposed tools are only the intersection of all four constraints, an out-of-allowlist or wildcard grant never expands access, and a tool lacking its required permission is denied before execution.
+  - id: AGENTS-LIFECYCLE
+    given: An agent definition, procedure, or provider connection is no longer needed.
+    when: An authorized manager archives or deletes it.
+    then: Archiving records an audit event and prevents unsafe future use; deletion checks the trusted tenant, current revision, CSRF, and all active references without cascading run evidence or assignments.
+  - id: AGENTS-WEB-SEARCH
+    given: An agent has web search disabled or lacks the registered web search permission and grant.
+    when: A model requests web search.
+    then: The harness denies the call and persists a safe denial event without making a network request.
+  - id: AGENTS-STREAM
+    given: A claimed run is producing model text or tool events.
+    when: An authorized client observes the run event stream.
+    then: Ordered persisted deltas and lifecycle events arrive without exposing credentials, hidden provider reasoning, or cross-tenant data.
+  - id: AGENTS-RUN-GRANT
+    given: A worker owns a live lease for a claimed run.
+    when: It requests provider execution.
+    then: A signed run grant is issued, atomically consumed once by the provider broker, recorded without its token, and rejected on replay or lease mismatch without returning provider credentials.
+  - id: AGENTS-LONG-RUN
+    given: An active agent has a bounded execution timeout of up to 24 hours.
+    when: Its run continues after the initiating browser closes or session expires.
+    then: The worker renews the lease and the persisted run continues independently until completion, bounded failure, or recoverable process interruption.
+  - id: AGENTS-WORKFLOW-TRIGGER
+    given: A workflow node references an active agent and supplies an idempotency key, bounded input, tenant, and approved execution principal.
+    when: The workflow enqueues agent work.
+    then: The same durable run contract returns immediately and the workflow can resume from the terminal run event.
+  - id: AGENTS-TEMPLATE
+    given: An agent definition whose instructions embed run context variables such as context.tenantName and context.today.
+    when: An authorized principal queues a run.
+    then: The run snapshot carries the instructions resolved to the active tenant, requesting principal, and UTC date while the stored definition keeps the raw template.
+  - id: AGENTS-AUDIT-READ
+    given: A principal reads the agent audit trail over HTTP.
+    when: The principal lacks agents.runs.read, or holds it and pages with a cursor.
+    then: The request is denied before any row is read without the scope, and with it only the active tenant's events are returned newest first with a stable occurred-at and sequence cursor and the chain fields.
+  - id: AGENTS-AUDIT-VERIFY
+    given: A stored agent audit row is altered after it was written.
+    when: A principal with agents.runs.read verifies the chain over HTTP, reusing the same walk as the audit-verify CLI.
+    then: The response reports the chain as not verified and names the identifier of the first broken row.
+  - id: AGENTS-COST
+    given: A run completes and reports its token usage.
+    when: The run is settled.
+    then: Its cost is written in the same transaction from the published price of its model, or left unpriced when the model has none, and appears in the tenant's per-day and per-agent rollups.
+  - id: AGENTS-BUDGET
+    given: A tenant or per-agent monthly budget is configured and the month's settled cost has reached it.
+    when: A further run is enqueued.
+    then: The enqueue is refused with a stable budget code before any provider call, while runs already executing continue to completion.
+  - id: AGENTS-EXACT-REVISION
+    given: A workflow references an active retained agent revision and that agent is edited later.
+    when: The workflow enqueues the pinned revision.
+    then: The run uses the retained instructions, procedures, tools, provider, model, and limits exactly as saved for that revision.
+  - id: AGENTS-MODULE-WORKFLOW
+    given: A published workflow pins an active executable revision of a module-owned agent.
+    when: The module later registers a higher definition revision or a tenant manager changes its provider binding.
+    then: The published workflow continues to resolve the retained executable revision, while newly published workflows can select the new current revision.
+  - id: AGENTS-STRUCTURED-OUTPUT
+    given: A workflow requests JSON output with a bounded schema from a pinned provider model that supports structured output.
+    when: The provider completes the run.
+    then: The harness validates the structured value against the schema before the worker persists it, and a missing or invalid value fails with a stable code.
+  - id: AGENTS-WORKFLOW-OBSERVE
+    given: A workflow enqueued an exact agent revision with a stable idempotency key.
+    when: It observes events, reads the result, retries enqueue, or requests cancellation.
+    then: It sees only the same tenant and workflow run, retry returns the original run, events remain ordered, and cancellation does not cross an actor or tenant boundary.
+  - id: AGENTS-VERSIONED-ACTION
+    given: A registered tool opts into workflow use with schemas, a positive contract version, read or workspace-write risk, required idempotency, and a cancellation policy.
+    when: A workflow starts the action with a trusted actor and sufficient permission snapshot.
+    then: The invocation is persisted before execution, repeated input returns the original invocation, different input conflicts, and output is schema checked before settlement.
+  - id: AGENTS-ACTION-DENY
+    given: A tool is destructive, external, incomplete, targets another tenant, lacks a required permission, or receives invalid input.
+    when: A workflow attempts to list, start, observe, or cancel it.
+    then: The capability excludes or refuses it before execution without exposing secrets, cross-tenant state, or raw payloads in audit metadata.
+  - id: AGENTS-SERVICE-ACTOR
+    given: A schedule, webhook, or other service identity was configured by an authenticated user.
+    when: It initiates workflow agent work or a versioned action.
+    then: Durable state records the service actor and its configuring user so history never presents background work as an anonymous system mutation.
+  - id: AGENT-CHILD-ISOLATION
+    given: Two workspaces each own an agent run with procedure snapshots and a provider connection with model readiness.
+    when: A caller supplies the other workspace's run id or provider id directly.
+    then: The read returns nothing, because those child tables carry their own workspace and force row-level security rather than relying on their parent.

package/modules/agents/spec/procedures-compatibility.md

@@ -0,0 +1,63 @@
+# Procedures compatibility plan
+
+This note accompanies the draft `agents.core` 0.8.0 specification. It changes
+the business product term from **Skills** to **Procedures**. Coding-agent skill
+catalogs in `.ai/skills` and `.agents/skills` are unrelated and keep their
+current names.
+
+## Canonical 0.8 contract
+
+| Concern             | Canonical procedure contract                                                                 | Compatibility surface                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Domain              | `AgentProcedure`, `AgentProcedureStatus`, `AgentProcedureSnapshot`, `AgentRevisionProcedure` | Deprecated `AgentSkill*` type aliases                                                  |
+| Agent configuration | `procedureIds`                                                                               | Deprecated `skillIds` accepted and returned during the compatibility window            |
+| Retained run data   | `procedureSnapshots` and `procedures` in executable revisions                                | Deprecated `skillSnapshots` and `skills` projections of the same immutable values      |
+| Collection response | `procedures`                                                                                 | Deprecated `skills` field containing the same records                                  |
+| Mutations           | `/api/agent-procedures`, `/update`, `/archive`, `/delete`; response envelope `procedure`     | Existing `/api/agent-skills` routes and `skill` envelope call the same service methods |
+| Client route        | `agent-procedures`                                                                           | `agent-skills` remains a hidden deep-link alias                                        |
+| Permission labels   | Procedures                                                                                   | `agents.skills.read` and `agents.skills.manage` identifiers remain stable              |
+| Persistence         | Procedure repository and service method names                                                | Existing `agent_skills`, assignment, and snapshot tables remain the physical storage   |
+| Audit display       | Procedure                                                                                    | Historical `agent-skill.*` action and subject identifiers remain unchanged             |
+
+Canonical and deprecated routes must share validation, authorization, CSRF,
+tenant isolation, optimistic concurrency, lifecycle checks, and audit writes.
+Calling both surfaces with the same id cannot create duplicate resources or
+independent revision histories.
+
+## Data safety
+
+Version 0.8 does not rename or copy database tables. A name-only schema rewrite
+would make rollback to an older binary unsafe and would add no data capability.
+The repository treats the existing tables as a private compatibility detail.
+Existing ids, assignments, retained revision JSON, run snapshots, migration
+checksums, and audit hashes stay byte-for-byte intact.
+
+The persisted permission ids also remain stable because tenant grants live in
+`auth.core`. Product labels and descriptions say Procedures, while authorization
+continues to evaluate the existing ids. A future permission-id migration would
+need a separate cross-module specification and dual-grant rollout.
+
+## Compatibility window
+
+The skill-named HTTP routes, JSON fields, and exported TypeScript aliases remain
+deprecated for the full 0.x line. New Flowdular clients use only the procedure
+contract. Removal requires a major contract version, repository-wide consumer
+search, and an explicit migration guide.
+
+Physical table names and historical audit identifiers may remain indefinitely.
+They are not user-facing and changing them would weaken rollback and evidence
+integrity.
+
+## Verification required before approval can land
+
+1. Existing fixtures created before 0.8 list, update, archive, execute,
+   and delete the same records through the procedure API without a data copy.
+2. Canonical and deprecated mutation routes enforce identical 401, 403, CSRF,
+   tenant, validation, conflict, and lifecycle behavior.
+3. Agent execution snapshots the selected procedure revision and required tools,
+   including an agent stored previously with skill-named assignments.
+4. The Procedures navigation, form, table, empty state, confirmation dialogs,
+   agent definition form, and accessibility labels contain no product-facing
+   use of Skill.
+5. English and Polish bundles have identical keys, and the former deep link
+   resolves to the Procedures view without a second navigation item.

package/modules/agents/src/acl/permissions.ts

@@ -0,0 +1,13 @@
+export const AGENT_PERMISSIONS = {
+	definitionsRead: 'agents.definitions.read',
+	definitionsManage: 'agents.definitions.manage',
+	runsRead: 'agents.runs.read',
+	runsExecute: 'agents.runs.execute',
+	providersRead: 'agents.providers.read',
+	providersManage: 'agents.providers.manage',
+	providersTest: 'agents.providers.test',
+	/* Product term is Procedures. The identifiers keep their skill-era
+	   spelling so existing tenant grants stay valid. */
+	proceduresRead: 'agents.skills.read',
+	proceduresManage: 'agents.skills.manage',
+} as const;