ai-capability-framework 1.0.3 → 1.1.0

package/docs/getting-started/provider-neutral-quickstart.md

@@ -1,106 +1,265 @@
 # Provider-Neutral Quickstart
 
-Use this path first if you want to understand AICF without choosing a model provider. It
-uses the public support/refund examples and does not require API keys, provider SDKs,
-live calls, or credentials.
+Start in an empty project with Node.js 20, 22 or 24 and npm. This walkthrough uses
+synthetic data and a deterministic mock model: no API key, provider SDK, source checkout
+or framework build is required.
 
-## What You Will Prove
+## 1. Install
 
-- Capability manifests can describe app functionality without provider-specific schemas.
-- AICF can validate the registry and inspect the capability set.
-- Deterministic decisions and evals run without calling a model.
-- Provider adapters are optional layers over the same AICF contracts.
-
-## 1. Install And Build
-
-```bash
-npm ci
-npm run build
+```sh
+mkdir aicf-example
+cd aicf-example
+npm init -y
+npm install ai-capability-framework
 ```
 
-Expected output excerpt:
-
-```text
-added ... packages
-tsc -p tsconfig.json
+The stable package includes discovery. Your ordinary model/tool loop chooses among
+eligible tools; lexical discovery makes no model or embedding calls.
+
+## 2. Describe your capability
+
+Create a `capabilities` directory. Save this as `capabilities/ticket.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "id": "support.ticket.get",
+  "version": "1.0.0",
+  "status": "active",
+  "name": "Read support ticket",
+  "summary": "Read a support ticket by ticket ID.",
+  "model_description": "Read a synthetic ticket the current user is allowed to view. Does not change data.",
+  "capability_type": "read_data",
+  "autonomy_tier": "A1",
+  "risk_tier": "low",
+  "input_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["ticket_id"],
+    "properties": { "ticket_id": { "type": "string", "pattern": "^TCK-[0-9]+$" } }
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["ticket_id", "status"],
+    "properties": { "ticket_id": { "type": "string" }, "status": { "type": "string" } }
+  },
+  "side_effects": {
+    "reads_data": true,
+    "writes_data": false,
+    "creates_records": false,
+    "updates_records": false,
+    "deletes_records": false,
+    "sends_external_messages": false,
+    "charges_money": false,
+    "refunds_money": false,
+    "changes_permissions": false,
+    "triggers_external_workflow": false,
+    "irreversible": false
+  },
+  "authorization": {
+    "permissions": ["ticket.read"],
+    "tenant_scoped": true,
+    "requires_user_context": true
+  },
+  "policy": { "approval_required": false, "max_autonomy_tier": "A1" },
+  "lifecycle": {
+    "prepare": false,
+    "preview": false,
+    "approve": false,
+    "commit": false,
+    "verify": false,
+    "audit": true
+  },
+  "observability": { "log_inputs": "redacted", "log_outputs": "summary" }
+}
 ```
 
-## 2. Inspect A Capability Manifest
-
-Open `examples/support/capabilities/support.ticket.get.yaml`. It defines a read-only
-support ticket capability with input/output schemas, permissions, risk, status, and
-lifecycle metadata.
-
-The important point is that the manifest is provider-neutral. It is not an OpenAI,
-Anthropic, Gemini, MCP, LangChain, or AI SDK schema.
-
-## 3. Validate Public Examples
-
-```bash
-npm run validate
+The manifest describes the contract; your handler supplies the implementation.
+Production identity and permissions must come from trusted host authentication. Handlers
+must enforce access to the requested resource within that tenant.
+
+## 3. Load, discover and execute
+
+Save this as `app.mjs`:
+
+```js
+import {
+  buildRegistry,
+  loadManifests,
+  validateManifests,
+  toOpenAIResponsesToolName
+} from "ai-capability-framework";
+import { createCapabilityDiscovery } from "ai-capability-framework/discovery";
+import {
+  AicfHandlerRegistry,
+  AicfToolExecutor,
+  AicfActionLifecycleManager,
+  DefaultContextBuilder,
+  DefaultPolicyBroker,
+  InMemoryApprovalStore,
+  InMemoryIdempotencyStore,
+  InMemoryPreparedActionStore
+} from "ai-capability-framework/runtime";
+import {
+  MockOpenAIResponsesClient,
+  mockFunctionCallResponse,
+  mockTextResponse,
+  runOpenAIResponses
+} from "ai-capability-framework/openai";
+
+const loaded = await loadManifests({ path: "capabilities" });
+if (loaded.errors.length || !validateManifests(loaded.manifests).valid) {
+  throw new Error("Invalid capability manifests.");
+}
+const registry = buildRegistry(loaded.manifests);
+// Synthetic identity for this mock only. Production identity comes from your host.
+const runtimeContext = {
+  environment: "test",
+  runId: "run_example",
+  requestId: "request_example",
+  startedAt: new Date().toISOString(),
+  account: { accountId: "account_example", tenantId: "tenant_example" },
+  subject: {
+    actorType: "user",
+    userId: "user_example",
+    roles: [],
+    permissions: ["ticket.read"]
+  },
+  autonomy: {
+    autonomyTier: "A1",
+    maxRiskTier: "low",
+    allowSideEffects: false,
+    allowExternalMessages: false,
+    allowMoneyMovement: false,
+    allowPermissionChanges: false
+  },
+  facts: {},
+  metadata: {}
+};
+
+// Set up the existing runtime once. These example stores live in one process.
+const handlers = new AicfHandlerRegistry({ registry });
+let reads = 0;
+handlers.register({
+  capabilityId: "support.ticket.get",
+  read: ({ args }) => {
+    reads += 1;
+    return { ticket_id: args.ticket_id, status: "open" };
+  }
+});
+const policyBroker = new DefaultPolicyBroker();
+const actionLifecycle = new AicfActionLifecycleManager({
+  registry,
+  handlers,
+  policyBroker,
+  approvalStore: new InMemoryApprovalStore(),
+  idempotencyStore: new InMemoryIdempotencyStore(),
+  preparedActionStore: new InMemoryPreparedActionStore()
+});
+const executor = new AicfToolExecutor({
+  registry,
+  handlers,
+  policyBroker,
+  actionLifecycle
+});
+
+const task = { id: "read-ticket", text: "Read ticket TCK-100." };
+const discovery = createCapabilityDiscovery({ registry });
+const [result] = await discovery.search({ tasks: [task], runtimeContext });
+if (result.status !== "matched")
+  throw new Error("No actionable shortlist; clarify or handle the failure.");
+const client = new MockOpenAIResponsesClient([
+  mockFunctionCallResponse({
+    name: toOpenAIResponsesToolName("support.ticket.get"),
+    callId: "read_example",
+    args: { ticket_id: "TCK-100" }
+  }),
+  mockTextResponse("Ticket TCK-100 is open.")
+]);
+const loop = await runOpenAIResponses({
+  registry,
+  executor,
+  client,
+  model: "mock-model",
+  runtimeContext,
+  contextBuilder: new DefaultContextBuilder(),
+  userInput: { text: task.text },
+  router: discovery.routerFor(result),
+  maxToolCalls: 1,
+  maxTurns: 2
+});
+if (
+  loop.status !== "completed" ||
+  reads !== 1 ||
+  loop.toolResults[0]?.status !== "success"
+) {
+  throw new Error("The mock read did not complete.");
+}
+console.log(
+  JSON.stringify(
+    {
+      queryId: result.queryId,
+      capabilityId: loop.toolCalls[0].capabilityId,
+      toolStatus: loop.toolResults[0].status,
+      data: loop.toolResults[0].data,
+      reads,
+      ordinaryModelTurns: client.requests.length,
+      discoveryProviderCalls: result.usage.totals.providerAttempts
+    },
+    null,
+    2
+  )
+);
 ```
 
-Expected output excerpt:
+Run the installed CLI and app:
 
-```text
-Validated 16 manifest(s) and 18 fixture(s).
+```sh
+npx aicf validate capabilities
+node app.mjs
 ```
 
-## 4. Inspect The Registry
+The CLI validates one manifest. The app reports `queryId: "read-ticket"`,
+`capabilityId: "support.ticket.get"`, `toolStatus: "success"`, one read, two mocked
+ordinary-model turns and zero discovery-provider calls. The ticket is `TCK-100` with
+status `open`. No real provider calls occur.
 
-```bash
-node dist/cli.js inspect examples
-```
-
-Expected output excerpt:
-
-```text
-Capabilities:
-- support.ticket.get
-- support.refund.prepare_case
-- support.refund.commit_case
-```
+## 4. Try the complete customer request
 
-## 5. Run A Deterministic Decision
+Run the packaged example from this same project:
 
-```bash
-node dist/cli.js decide examples --request examples/support/decisions/support.ticket.get.select.json
+```sh
+node node_modules/ai-capability-framework/examples/12-capability-discovery-selection/run-customer-mock.mjs
 ```
 
-Expected output excerpt:
-
-```text
-allowed: true
-capability: support.ticket.get
-```
-
-This proves the policy/selection path without a model. The request uses a synthetic
-user, tenant, permissions, and arguments.
-
-## 6. Run Deterministic Evals
-
-```bash
-node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
-```
-
-Expected output excerpt:
-
-```text
-Eval suite passed
-```
-
-The eval runner checks expected selected capabilities, tool calls, arguments,
-approval-required behavior, and no-commit boundaries from public fixtures. It does not
-call a provider.
-
-## 7. Export Provider Descriptors Later
-
-When you are ready to connect a provider, choose a runtime from
-[Choose a Runtime](../providers/choose-a-runtime.md). The provider adapter will export a
-routed AICF capability slice, but AICF validation and policy remain the authority.
-
-Useful next steps:
-
-- [OpenAI quickstart](openai-quickstart.md)
-- [Anthropic quickstart](anthropic-quickstart.md)
-- [Gemini quickstart](gemini-quickstart.md)
+It models “Read ticket TCK-100 and prepare a refund for its order.” Application code
+searches each ready task once, carries the authorized order ID to its dependent task,
+then prepares a preview requiring approval. Expect one mocked planning turn, four
+ordinary-model turns, one read, one preparation and zero commits. The customer response
+explains that approval is still pending. Dependencies and response assembly belong to
+the example application, not a framework workflow engine.
+
+## Connect your model and application
+
+Keep the same task text and invocation context when passing a result-bound router to
+your ordinary runner. Do not reconstruct, persist or reuse results across requests.
+Permissions, controls, source changes, cancellation and expiry are rechecked before
+export and execution. A retrieval score never authorizes an action.
+
+Replace the mock with your configured Responses-compatible client and an explicit model
+when using `runOpenAIResponses`; the framework supplies no account, credentials or model
+default. Existing configured clients need no additional discovery model. The optional
+OpenAI SDK is needed only if your application chooses it. See the
+[OpenAI quickstart](openai-quickstart.md) or
+[choose another runtime](../providers/choose-a-runtime.md).
+
+For `no_match`, clarify; for `unavailable` or `cancelled`, handle the operational
+outcome. Do not execute the first candidate automatically. Lexical/native is
+recommended. [Dedicated selection](../discovery.md#optional-dedicated-selection) is
+optional; hybrid is experimental with
+[qualification limits](../evals/discovery-qualification.md).
+
+The [stable workflow contract](../api/stable-workflow.md) defines compatibility for this
+path. Production authentication, resource access checks and durable stores remain
+host-owned. [Repository development](../development.md) is separate from package use.

package/docs/getting-started/quickstart.md

@@ -1,32 +1,10 @@
 # Quickstart
 
-The fastest path is the public support/refund walkthrough:
-
-```bash
-npm install
-npm run build
-npm run validate
-node dist/cli.js inspect examples
-node dist/cli.js openai-tools examples --context examples/support/openai/context.support_agent.json
-node examples/runtime-support-billing/run-mock.mjs
-node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
-```
-
-Expected output excerpts:
-
-```text
-Validated 16 manifest(s) and 18 fixture(s).
-Manifests: 16 (6 capabilities, 4 entities, 6 evals)
-approval_required
-Eval suite passed
-```
-
-What this proves:
-
-- manifests and fixtures validate;
-- read/prepare tools can be exported without exposing commit tools;
-- the runtime can read, prepare, require approval, and commit through host lifecycle
-  APIs;
-- evals prove expected behavior without calling a model.
-
-Full command explanations are in [Start here](../start-here.md).
+Start with the [installed-package walkthrough](provider-neutral-quickstart.md). From an
+empty project it shows a complete manifest, registry loading, runtime context, handler,
+lexical discovery and ordinary mocked tool execution. No checkout or provider key is
+required.
+
+The same guide runs the complete dependent read/prepare customer example and explains
+approval requirements. See [repository development](../development.md) only when
+changing the framework itself.

package/docs/index.md

@@ -73,3 +73,13 @@ Models propose; applications validate, authorize, execute, and audit.
 - [Security disclosure](public-framework/security-disclosure.md)
 - [API reference](api.md)
 - [Public API policy](api/public-api-policy.md)
+
+## Capability discovery
+
+The optional `ai-capability-framework/discovery` API provides a
+[stable lexical/native workflow](api/stable-workflow.md), a simple search facade,
+result-bound routers, explicit hybrid retrieval and dedicated selection, and
+provider-free evaluation. Start with [finding capabilities for a task](discovery.md).
+For opt-in provider evaluation, see the
+[discovery live evaluation guide](evals/discovery-live.md) and the
+[qualification results and limits](evals/discovery-qualification.md).

package/docs/release.md

@@ -2,6 +2,29 @@
 
 This checklist prepares an AICF public release for GitHub and npm distribution.
 
+## Stable discovery workflow
+
+The [named lexical/native workflow](api/stable-workflow.md) is stable public in 1.1.0.
+Advanced APIs retain their individual maturity labels. Recommend lexical retrieval with
+ordinary model tool selection; dedicated selection is optional and hybrid remains
+experimental. Link the [qualification report](evals/discovery-qualification.md) in
+release notes. Its qualified lexical results apply to a tested synthetic configuration,
+and the revised workflow assessment is an offline checker correction rather than new
+live trials.
+
+Use a reviewed pull request, passing hosted Linux Node 20/22/24 checks, merge, and an
+exact-commit manual release dry-run before pushing the matching version tag. Local
+checks do not replace hosted checks. Prereleases publish both packages to `next`,
+preserving `latest` for prereleases. Stable 1.1.0 publishes to `latest` while preserving
+the existing `next` tag and prerelease versions. Verify normal installation as well as
+exact-version registry installs.
+
+The publication and dry-run workflows run `npm run check` plus certification with
+`VITEST_MAX_WORKERS=2`. Publication is serialized; registry failures fail closed unless
+npm explicitly reports E404 for an absent version. Local npm login is not the OIDC
+publishing mechanism. Verify package ownership and the trusted publisher for both
+packages before tagging; never substitute a stored npm token.
+
 ## Preflight
 
 - Confirm the release branch contains only public framework material.
@@ -261,11 +284,12 @@ npm view "ai-capability-framework@${VERSION}" version
 npm view "@aicf/agent-skills@${VERSION}" version
 ```
 
-If only `@aicf/agent-skills` published, fix the workflow or npm ownership issue and
-retry the root package publish at the same version from the same tag. If only the root
-package published, retry the agent-skills publish at the same version from the same tag.
-Do not move the public tag, delete the published version, or reuse a published npm
-version as a normal recovery path.
+If only one package published, mark the release incomplete and inspect its registry
+metadata before taking further action. The ordinary workflow rejects already-published
+targets, so do not blindly rerun it. Use a new coordinated release candidate when the
+existing workflow cannot safely complete the missing package. Do not move the public
+tag, delete the published version, or reuse a published npm version as a normal recovery
+path.
 
 If the tagged code is wrong, or if the failed package cannot be safely published from
 the same commit, bump both package versions and ship a follow-up patch or release

package/docs/runtime.md

@@ -1,5 +1,10 @@
 # Runtime Contracts
 
+The [named lexical/native workflow](api/stable-workflow.md) and its required runtime
+members are stable public from 1.1.0. Other runtime APIs retain their existing maturity;
+this does not promote every export. Start with the
+[installed-package walkthrough](getting-started/provider-neutral-quickstart.md).
+
 AICF Runtime is an additive TypeScript subpath for host applications that want
 deterministic runtime context, capability routing, policy brokering, handler execution,
 action lifecycle control, and model-safe tool result envelopes.
@@ -89,6 +94,12 @@ are incompatible with active read-only controls.
 Use `formatCapabilitySliceForModel()` to render concise model-facing capability guidance
 without private diagnostics, internal policy rules, or full output schemas.
 
+`filterEligibleCapabilities(request)` exposes the same runtime eligibility filters
+without ranking or count truncation. It returns `eligible` manifests in registry order
+and `excluded` capability IDs with their existing reasons. The default router uses this
+helper before scoring and applying its capability limit. Eligibility is a request-time
+filter; normal execution authorization still applies.
+
 ## Policy Broker
 
 `DefaultPolicyBroker` wraps the Core `decideCapability()` control plane and adds runtime
@@ -167,3 +178,19 @@ node examples/runtime-support-billing/run-mock.mjs
 It loads the support manifests, routes read and prepare capabilities, executes a ticket
 read, prepares a refund case that requires approval, records a host approval, and
 commits only through `AicfActionLifecycleManager`.
+
+### Optional shared provider runs
+
+`createAicfProviderRun` joins explicitly managed application planning, discovery,
+selection, and Responses tool-loop calls under one reservation ledger and absolute
+deadline. Its immutable snapshots retain unknown usage, pending work, and unique
+attempts. The default router and ordinary runner calls remain source-compatible. See the
+[shared-run example](../examples/12-capability-discovery-selection/README.md#shared-run-integration)
+for task-bound routing, optional selection, metadata tracing, and offline replay.
+
+## Optional capability discovery
+
+Use [capability discovery](discovery.md) to retrieve an eligible shortlist and pass its
+result-bound router to an ordinary model/tool runner. The optional discovery subpath
+preserves runtime authorization and read/prepare boundaries; default routing stays
+unchanged. Dedicated model selection is explicitly invoked.

package/docs/start-here.md

@@ -1,136 +1,25 @@
 # Start Here
 
-This guide shows the smallest useful AICF path with the public support/refund example.
-It is API-key-free and uses synthetic data only.
-
-You will validate manifests, inspect the registry, export OpenAI tools, run the mock
-runtime flow, and score evals.
-
-## 1. Install
-
-```bash
-npm install
-```
-
-This installs the local package dependencies. It does not install provider SDKs or call
-any model.
-
-## 2. Validate The Public Examples
-
-```bash
-npm run validate
-```
-
-Expected excerpt:
-
-```text
-Validated 16 manifest(s) and 18 fixture(s).
-```
-
-This proves the public manifests and fixture files are parseable, schema-valid,
-cross-referenced, and public-safe enough for the validation rules.
-
-## 3. Inspect The Registry
-
-Build the CLI, then inspect the examples:
-
-```bash
-npm run build
-node dist/cli.js inspect examples
-```
-
-Expected excerpt:
-
-```text
-AICF Registry
-Manifests: 16
-Capabilities by type:
-- read_data: scheduling.availability.get, support.ticket.get
-- write_prepare_only: scheduling.invite.prepare, support.refund.prepare_case
-- write_commit: scheduling.invite.send, support.refund.commit_case
-```
-
-This shows the validated registry AICF uses for routing, provider export, policy
-decisions, and eval scoring.
-
-## 4. Export OpenAI Tools
-
-```bash
-node dist/cli.js openai-tools examples --context examples/support/openai/context.support_agent.json
-```
-
-Expected excerpt:
-
-```json
-{
-  "tools": [
-    {
-      "type": "function",
-      "name": "aicf_support_refund_prepare_case",
-      "strict": true
-    },
-    {
-      "type": "function",
-      "name": "aicf_support_ticket_get",
-      "strict": true
-    }
-  ],
-  "excluded": [
-    {
-      "capabilityId": "support.refund.commit_case"
-    }
-  ]
-}
-```
-
-This proves safe tool export. The model can see read and prepare tools, but the commit
-capability is not exposed as a normal model tool.
-
-## 5. Run The Mock Runtime Flow
-
-```bash
-node examples/runtime-support-billing/run-mock.mjs
-```
-
-Expected excerpt:
-
-```json
-{
-  "readStatus": "success",
-  "prepareStatus": "approval_required",
-  "commitStatus": "committed"
-}
-```
-
-This runs route, read, prepare, approval, and lifecycle commit with mock handlers and
-in-memory reference stores. The model-facing path still cannot commit. Commit happens
-only after the host records approval and calls the lifecycle manager.
-
-## 6. Run Deterministic Evals
-
-```bash
-node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
-```
-
-Expected excerpt:
-
-```text
-Eval suite passed: 6/6 passed.
-```
-
-This proves the candidate fixture matches the eval manifests for tool selection,
-arguments, policy decisions, refusals, response text, and no unapproved commit
-boundaries.
-
-## What You Just Proved
-
-- Public manifests validate and build a registry.
-- OpenAI tool export is safe and does not expose commit tools by default.
-- Provider SDK validation does not replace AICF validation.
-- The runtime can execute read and prepare handlers with model-safe envelopes.
-- Approval-required prepare pauses before side effects.
-- Host-controlled lifecycle commit works after approval and idempotency checks.
-- Evals score behavior without calling models.
-
-Next, read the [OpenAI walkthrough](openai-walkthrough.md) for the same flow from the
-model/tool-call perspective, then use the [glossary](glossary.md) for the main terms.
+Install with `npm install ai-capability-framework`, then follow the
+[complete installed-package quickstart](getting-started/provider-neutral-quickstart.md).
+It needs no checkout, provider SDK or API key.
+
+You will author one capability, load its registry, create runtime context, register a
+handler, search a task and execute the ordinary mock model/tool loop. The packaged
+customer example then shows an authorized read followed by an approval-required preview.
+
+Lexical/native is the recommended [stable workflow](api/stable-workflow.md). Dedicated
+selection is optional; hybrid remains experimental with
+[qualification limits](evals/discovery-qualification.md). Applications own
+decomposition, dependencies, arguments, authentication, resource access and customer
+responses.
+
+The model can see read and prepare tools, but the commit capability is not exposed.
+Runtime validation, authorization and approval policy remain the authority for actions.
+
+- [Installation](getting-started/installation.md)
+- [Capability manifests](capability-manifests.md)
+- [Choose a runtime](providers/choose-a-runtime.md)
+- [Discovery details](discovery.md)
+- [API policy](api/public-api-policy.md)
+- [Repository development](development.md)