ai-capability-framework 1.0.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable public changes to AI Capability Framework are documented here.
+
+## 1.0.0-rc.1 - 2026-06-03
+
+1.0 spec-complete release candidate.
+
+- Promoted public manifests and eval result fixtures to
+  `schema_version: "1.0"`.
+- Made the spec normative and explicit about the no-execution boundary.
+- Added migration, host responsibility, and interoperability guidance.
+- Added a second synthetic domain and conformance fixtures for external review.
+- Added no-model-call adapters for Anthropic Claude, Google Gemini, Vercel AI
+  SDK, Model Context Protocol, LangChain/LangGraph, and Semantic Kernel.
+- Enabled public npm release-candidate publishing while keeping the no-execution
+  framework boundary.
+
+## 0.1.0 - 2026-06-03
+
+Initial public v0.1 release candidate.
+
+- Added JSON Schema contracts for capability, entity, eval case, and eval result
+  manifests.
+- Added synthetic support examples for read, prepare-only write, commit, policy,
+  approval, refusal, and eval boundaries.
+- Added a TypeScript core library and `aicf` CLI for loading, validating,
+  inspecting, deciding, OpenAI tool export, and deterministic eval scoring.
+- Added deterministic policy and lifecycle decision APIs without executing
+  capabilities or performing side effects.
+- Added a no-model-call OpenAI Responses adapter for exporting function tool
+  definitions and parsing tool calls.
+- Added an API-key-free eval runner for scoring candidate result fixtures.
+- Added release-readiness package checks, public API docs, CI validation, and
+  public repository boundary guidance.
+
+This release was GitHub-release-ready only and was not published to npm.

package/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thanks for improving AI Capability Framework. This repository is public, so
+every tracked change must be safe to publish.
+
+## Public-Safe Contributions
+
+- Use synthetic examples with fake IDs, fake tenants, fake users, and
+  `example.com` addresses.
+- Do not commit credentials, account IDs, customer records, raw prompts, raw
+  traces, provider payloads, private source documents, generated exports, or
+  local experiments.
+- Keep private notes and drafts in `_private/` or another ignored path.
+- Never copy from `_private/` into tracked files verbatim. Distill public
+  guidance in new wording.
+
+## Development Workflow
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+Common commands:
+
+```bash
+npm run generate:types
+npm run check:generated
+npm run build
+npm test
+npm run validate
+npm run check:package
+npm run check
+```
+
+Run `npm run generate:types` whenever schemas change. Generated public manifest
+types under `src/generated/` must stay current.
+
+## Pull Requests
+
+Before opening a pull request:
+
+- Run `npm run check`.
+- Confirm examples are public-safe and synthetic.
+- Confirm `_private/`, traces, prompts, provider payloads, generated local docs,
+  packed tarballs, and local-only files are not tracked.
+- Use `git status --short --ignored` to confirm private material remains
+  ignored.
+- Use `git ls-files` to inspect the tracked public surface.
+
+## Scope
+
+AICF 1.0 is a no-execution framework. Contributions should not add model calls,
+handler registries, action stores, approval runtimes, or side effects unless a
+future roadmap explicitly changes that boundary.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Capability Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# AI Capability Framework
+
+AI Capability Framework (AICF) is a small public framework for describing what an
+AI-enabled application is allowed to know, decide, and do.
+
+The repository contains:
+
+- JSON Schema contracts for capability, entity, and eval manifests.
+- Synthetic examples that show how to describe a capability without exposing
+  private application internals.
+- A TypeScript core library and `aicf` CLI for loading, validating, and
+  inspecting manifests.
+- Provider and runtime adapters that export safe tool descriptors without
+  calling models or executing capabilities.
+- A deterministic eval runner for scoring public-safe candidate fixtures
+  without API keys or live model calls.
+- A normative `1.0` public spec for capability IDs, tiers, lifecycle, and
+  public-safe examples.
+
+## Why This Exists
+
+AI products are easier to govern when model-facing behavior is represented as
+explicit application capabilities instead of broad tool lists or hidden prompts.
+AICF separates semantic interpretation from deterministic application control:
+
+- Models interpret the user goal and select from a small set of relevant
+  capabilities.
+- Application code validates inputs, checks authorization, enforces policy,
+  executes side effects, and records audit evidence.
+- Evals verify that capability selection, tool arguments, approval boundaries,
+  and safety behavior remain stable.
+
+## Quick Start
+
+Install dependencies and validate the public examples:
+
+```bash
+npm install
+npm run validate
+```
+
+Inspect the public example registry:
+
+```bash
+npm run inspect
+```
+
+Evaluate a deterministic capability decision:
+
+```bash
+npm run build
+node dist/cli.js decide examples --request examples/support/decisions/support.refund.prepare_case.approval_required.json
+```
+
+Export OpenAI Responses function tools from a validated registry:
+
+```bash
+npm run build
+node dist/cli.js openai-tools examples --context examples/support/openai/context.support_agent.json
+```
+
+Export another adapter shape:
+
+```bash
+npm run build
+node dist/cli.js anthropic-tools examples --context examples/support/openai/context.support_agent.json
+```
+
+Run deterministic evals against a public-safe candidate fixture:
+
+```bash
+npm run build
+node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
+```
+
+Start a capability manifest excerpt:
+
+```yaml
+schema_version: "1.0"
+id: support.refund.prepare_case
+version: 1.0.0
+status: active
+name: Prepare refund case
+summary: Prepare a refund case for review without issuing money.
+capability_type: write_prepare_only
+autonomy_tier: A2
+risk_tier: medium
+```
+
+Then add the required input/output schemas, side-effect metadata,
+authorization rules, policy gates, lifecycle flags, observability settings, and
+eval references. Complete copyable examples live under `examples/`.
+
+## Repository Layout
+
+```text
+schemas/   JSON Schema contracts for AICF manifests
+examples/  Synthetic public example capabilities, entities, and evals
+conformance/ Public valid and invalid fixtures for contract review
+docs/      Public usage guidance
+src/       TypeScript core, CLI, generated types, and tests
+scripts/   Local type-generation utilities
+```
+
+Start with [the 1.0 spec](docs/spec.md), read the
+[API guide](docs/api.md), the [control-plane guide](docs/control-plane.md), the
+[OpenAI Responses adapter](docs/openai-responses.md), the
+[adapter guide](docs/adapters.md), the
+[eval runner guide](docs/eval-runner.md), the
+[host responsibilities guide](docs/host-responsibilities.md), and the
+[interoperability guide](docs/interoperability.md). For future provider and
+runtime adapters, see the [adapter roadmap](docs/adapter-roadmap.md), then
+inspect the examples.
+
+Release and collaboration docs:
+[CHANGELOG](CHANGELOG.md), [CONTRIBUTING](CONTRIBUTING.md),
+[SECURITY](SECURITY.md), the [migration guide](docs/migration-0.1-to-1.0.md),
+and the [release checklist](docs/release.md).
+
+Private drafts and source material are intentionally excluded from this public
+repository. See `AGENTS.md` for the tracking boundary used in this workspace.
+
+## Core Concepts
+
+Capability manifest:
+Describes a model-selectable application capability, including its input/output
+contract, risk tier, side effects, authorization requirements, policy gates, and
+observability expectations.
+
+Entity manifest:
+Describes an application entity that capabilities may read or act on. It records
+canonical identifiers, data classification, relationships, and model-facing
+guidance.
+
+Eval case:
+Describes a regression case for capability selection, argument extraction,
+approval boundaries, refusals, and safety behavior.
+
+Action lifecycle:
+Side-effecting capabilities should generally follow a prepare, preview, approve,
+commit, verify, and audit lifecycle. Low-risk read or compute capabilities can
+use simpler flows when policy allows it.
+
+## Validation
+
+`npm run validate` parses all schema files, then validates every YAML/JSON
+example under:
+
+- `examples/**/capabilities/`
+- `examples/**/entities/`
+- `examples/**/evals/`
+
+The script fails on malformed examples or schema violations.
+
+GitHub Actions runs type generation, generated-type freshness checks, build,
+tests, and validation on pushes and pull requests.
+
+## TypeScript API
+
+AICF exposes a small no-execution TypeScript surface:
+
+- `loadManifests(options)`
+- `validateManifests(manifests, options)`
+- `buildRegistry(manifests)`
+- `inspectRegistry(registry)`
+- `decideCapability(registry, request)`
+- `evaluatePolicy(capability, request)`
+- `evaluateLifecycle(capability, request)`
+- `buildOpenAIResponsesTools(registry, options)`
+- `parseOpenAIResponsesToolCall(toolset, call)`
+- `toOpenAIResponsesToolName(capabilityId, options)`
+- `buildAnthropicClaudeTools(registry, options)`
+- `parseAnthropicClaudeToolUse(toolset, toolUse)`
+- `buildGeminiFunctionDeclarations(registry, options)`
+- `parseGeminiFunctionCall(functionSet, functionCall)`
+- `buildAiSdkTools(registry, options)`
+- `parseAiSdkToolCall(toolset, toolCall)`
+- `buildMcpToolDescriptors(registry, options)`
+- `parseMcpToolCall(toolset, toolCall)`
+- `buildLangChainToolDescriptors(registry, options)`
+- `parseLangChainToolCall(toolset, toolCall)`
+- `buildSemanticKernelFunctions(registry, options)`
+- `parseSemanticKernelFunctionCall(functionSet, functionCall)`
+- `loadEvalResults(path)`
+- `scoreEvalCase(evalCase, candidate, registry)`
+- `runEvalSuite(registry, candidates, options)`
+
+Generated public types include `CapabilityManifest`, `EntityManifest`, and
+`EvalCase`. Decision types include `DecisionRequest`, `DecisionResult`,
+`DecisionReason`, `DecisionOperation`, and `DecisionStatus`. OpenAI adapter
+types include `OpenAIResponsesToolset`, `OpenAIResponsesFunctionTool`, and
+`OpenAIResponsesToolBinding`. Eval runner types include `EvalResultFixture`,
+`EvalCandidateResult`, `EvalSuiteResult`, `EvalCaseResult`, and
+`EvalScorerResult`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+AI Capability Framework is public. Please do not disclose secrets, customer
+data, raw prompts, raw traces, provider payloads, internal endpoints, or private
+documents in public issues, pull requests, or comments.
+
+## Reporting A Vulnerability
+
+Use GitHub private vulnerability reporting if it is enabled for this repository.
+If private reporting is unavailable, open a minimal public issue that describes
+the affected area at a high level and asks for a private reporting path. Do not
+include exploit details, credentials, real identifiers, or private data in that
+public issue.
+
+## What To Include Privately
+
+- Affected schema, API, CLI command, or documentation area.
+- Reproduction steps using synthetic data.
+- Expected and actual behavior.
+- Impact and suggested fix, if known.
+
+## Public Safety
+
+Security fixes should preserve the repository boundary:
+
+- Keep `_private/` ignored and untracked.
+- Redact or omit raw traces, prompts, and provider payloads.
+- Use synthetic examples only.
+- Run `npm run check` before handoff.

package/conformance/invalid/duplicate/capabilities/conformance.duplicate.one.yaml

@@ -0,0 +1,55 @@
+schema_version: "1.0"
+id: conformance.duplicate.get
+version: 1.0.0
+status: active
+name: Duplicate conformance note one
+summary: First intentionally duplicated capability ID.
+model_description: Read a synthetic note.
+capability_type: read_data
+autonomy_tier: A1
+risk_tier: low
+input_schema:
+  type: object
+  additionalProperties: false
+  required:
+    - note_id
+  properties:
+    note_id:
+      type: string
+output_schema:
+  type: object
+  additionalProperties: false
+  required:
+    - note_id
+  properties:
+    note_id:
+      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:
+    - note.read
+  tenant_scoped: true
+  requires_user_context: true
+policy:
+  approval_required: false
+lifecycle:
+  prepare: false
+  preview: false
+  approve: false
+  commit: false
+  verify: false
+  audit: true
+observability:
+  log_inputs: redacted
+  log_outputs: summary

package/conformance/invalid/duplicate/capabilities/conformance.duplicate.two.yaml

@@ -0,0 +1,55 @@
+schema_version: "1.0"
+id: conformance.duplicate.get
+version: 1.0.0
+status: active
+name: Duplicate conformance note two
+summary: Second intentionally duplicated capability ID.
+model_description: Read a synthetic note.
+capability_type: read_data
+autonomy_tier: A1
+risk_tier: low
+input_schema:
+  type: object
+  additionalProperties: false
+  required:
+    - note_id
+  properties:
+    note_id:
+      type: string
+output_schema:
+  type: object
+  additionalProperties: false
+  required:
+    - note_id
+  properties:
+    note_id:
+      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:
+    - note.read
+  tenant_scoped: true
+  requires_user_context: true
+policy:
+  approval_required: false
+lifecycle:
+  prepare: false
+  preview: false
+  approve: false
+  commit: false
+  verify: false
+  audit: true
+observability:
+  log_inputs: redacted
+  log_outputs: summary

package/conformance/invalid/eval-results/conformance.results.failing.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": "1.0",
+  "results": [
+    {
+      "eval_id": "conformance.note.get.valid",
+      "selected_capabilities": ["conformance.note.publish"],
+      "tool_calls": [],
+      "action_state": "committed",
+      "committed_capabilities": ["conformance.note.publish"],
+      "response": {
+        "text": "Committed an action that the eval forbids."
+      }
+    }
+  ]
+}

package/conformance/invalid/missing-reference/capabilities/conformance.missing_reference.prepare.yaml

@@ -0,0 +1,58 @@
+schema_version: "1.0"
+id: conformance.missing_reference.prepare
+version: 1.0.0
+status: active
+name: Missing reference fixture
+summary: Intentionally references a missing eval file.
+model_description: Prepare a synthetic conformance action.
+capability_type: write_prepare_only
+autonomy_tier: A2
+risk_tier: medium
+input_schema:
+  type: object
+  additionalProperties: false
+  required:
+    - note_id
+  properties:
+    note_id:
+      type: string
+output_schema:
+  type: object
+  additionalProperties: false
+  required:
+    - prepared_action_id
+  properties:
+    prepared_action_id:
+      type: string
+side_effects:
+  reads_data: true
+  writes_data: true
+  creates_records: true
+  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:
+    - note.prepare
+  tenant_scoped: true
+  requires_user_context: true
+policy:
+  approval_required: true
+lifecycle:
+  prepare: true
+  preview: true
+  approve: true
+  commit: false
+  verify: true
+  audit: true
+observability:
+  log_inputs: redacted
+  log_outputs: summary
+evals:
+  golden:
+    - ../evals/missing.conformance.eval.yaml

package/conformance/invalid/schema/capabilities/conformance.invalid.missing_required.yaml

@@ -0,0 +1,3 @@
+schema_version: "1.0"
+id: conformance.invalid.missing_required
+summary: This fixture is intentionally missing required capability fields.

package/conformance/valid/capabilities/conformance.note.get.yaml

@@ -0,0 +1,82 @@
+schema_version: "1.0"
+id: conformance.note.get
+version: 1.0.0
+status: active
+name: Get conformance note
+summary: Read a synthetic note used by public conformance fixtures.
+domain: conformance
+owner:
+  team: example-conformance
+  contact: conformance@example.com
+capability_type: read_data
+autonomy_tier: A1
+risk_tier: low
+model_description: >
+  Use this capability to retrieve a synthetic conformance note by ID.
+when_to_use:
+  - The user asks to read a conformance note.
+when_not_to_use:
+  - The user asks to change, delete, or publish a note.
+input_schema:
+  type: object
+  additionalProperties: false
+  required:
+    - note_id
+  properties:
+    note_id:
+      type: string
+      pattern: "^NOTE-[0-9]+$"
+output_schema:
+  type: object
+  additionalProperties: false
+  required:
+    - note
+  properties:
+    note:
+      type: object
+      additionalProperties: false
+      required:
+        - note_id
+        - title
+      properties:
+        note_id:
+          type: string
+        title:
+          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:
+    - note.read
+  tenant_scoped: true
+  requires_user_context: true
+  data_scope:
+    - current_tenant
+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
+  trace_attributes:
+    domain: conformance
+evals:
+  golden:
+    - ../evals/conformance.note.get.valid.yaml

package/conformance/valid/decisions/conformance.note.get.denied_missing_permission.json

@@ -0,0 +1,13 @@
+{
+  "capabilityId": "conformance.note.get",
+  "operation": "select",
+  "args": {
+    "note_id": "NOTE-1001"
+  },
+  "context": {
+    "autonomyTier": "A1",
+    "permissions": [],
+    "tenantId": "tenant_example",
+    "userId": "user_example_conformance"
+  }
+}

package/conformance/valid/entities/Note.yaml

@@ -0,0 +1,18 @@
+schema_version: "1.0"
+id: Note
+version: 1.0.0
+name: Note
+summary: A synthetic note used by public conformance fixtures.
+canonical_id:
+  field: note_id
+  pattern: "^NOTE-[0-9]+$"
+data_classification:
+  default: tenant_confidential
+  fields:
+    title: synthetic_note_title
+lookup:
+  primary_capability: conformance.note.get
+allowed_actions:
+  - conformance.note.get
+model_guidance: >
+  Notes in conformance fixtures are synthetic and tenant-scoped.

package/conformance/valid/eval-results/conformance.results.passing.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": "1.0",
+  "results": [
+    {
+      "eval_id": "conformance.note.get.valid",
+      "selected_capabilities": ["conformance.note.get"],
+      "tool_calls": [
+        {
+          "capability_id": "conformance.note.get",
+          "args": {
+            "note_id": "NOTE-1001"
+          }
+        }
+      ],
+      "action_state": "none",
+      "committed_capabilities": []
+    }
+  ]
+}