feat(agent): add package AgentFacts protocol

.changeset/plain-agents-report.md

@@ -0,0 +1,8 @@
+---
+"@sapiom/agent": minor
+---
+
+Add the package AgentFacts protocol with deterministic inventory-keyed
+normalization, authored schema and capability fields, allowlisted observed
+capabilities, explicit references, completeness diagnostics, and stable
+template summaries.

packages/agent/README.md

@@ -120,6 +120,20 @@ whether a permitted string contains a sensitive identifier. Graph evidence is
 explanatory metadata only: it cannot change execution, routing, authorization,
 deployment, builds, or billing.
 
+## Package AgentFacts
+
+`PackageInventory` is also the authority for per-agent factual metadata. The
+AgentFacts protocol emits one normalized record for every inventory `agentKey`;
+extractors must not rediscover, rename, or infer identity. Missing or partial
+cards become `unknown` or `partial` fields with diagnostics, not deleted agents.
+
+Supported facts are intentionally narrow: authored descriptions, exact
+input/output JSON Schemas, declared capabilities, observed capabilities from
+allowlisted structured capability-call observations, direct/source/evidence
+references, completeness, diagnostics, and deterministic template summaries.
+Unsupported observations are diagnosed and ignored, and semantic prose or
+relationships are never inferred from names or paths.
+
 ## The entry input contract
 
 A step's `inputSchema` (a zod schema, imported from `zod/v4`) types and validates that

packages/agent/package.json

@@ -49,7 +49,8 @@
     "prepublishOnly": "pnpm build"
   },
   "dependencies": {
-    "@sapiom/tools": "workspace:^"
+    "@sapiom/tools": "workspace:^",
+    "ajv": "^8.12.0"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.0.0"

packages/agent/src/index.ts

@@ -11,7 +11,14 @@
  */
 
 // Directives — the load-bearing protocol contract
-export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';
+export {
+  DIRECTIVE_KIND,
+  isContinue,
+  isRetry,
+  isPause,
+  isTerminate,
+  isFail,
+} from "./directives.js";
 export type {
   DirectiveKind,
   NextStepDirective,
@@ -20,16 +27,22 @@ export type {
   PauseUntilSignalDirective,
   TerminateDirective,
   FailDirective,
-} from './directives.js';
+} from "./directives.js";
 
 // Transition constructors + their branded types (the authoring surface)
-export { goto, terminate, fail, pauseUntilSignal, retry } from './directives.js';
-export type { Goto, Terminate, Fail, Pause, Retry } from './directives.js';
+export {
+  goto,
+  terminate,
+  fail,
+  pauseUntilSignal,
+  retry,
+} from "./directives.js";
+export type { Goto, Terminate, Fail, Pause, Retry } from "./directives.js";
 
 // Step authoring: defineStep + the derived `Allowed` return type + StepDefinition.
 // Step + StepResult are retained for the engine (deprecated for authoring).
-export { defineStep } from './step.js';
-export type { Step, StepResult, StepDefinition, Allowed } from './step.js';
+export { defineStep } from "./step.js";
+export type { Step, StepResult, StepDefinition, Allowed } from "./step.js";
 
 // Execution context — what a step's `run` receives (metadata + shared store + logger)
 export type {
@@ -39,18 +52,18 @@ export type {
   StepExecutionRecord,
   StepLogger,
   FinishedStepStatus,
-} from './context.js';
-export { InMemoryContextStore } from './context.js';
+} from "./context.js";
+export { InMemoryContextStore } from "./context.js";
 
 // Agent definition + defineAgent factory + brand guards (current + pre-rename legacy)
-export type { AgentDefinition } from './agent.js';
+export type { AgentDefinition } from "./agent.js";
 export {
   defineAgent,
   isAgentDefinition,
   AGENT_DEFINITION_BRAND,
   isLegacyOrchestrationDefinition,
   LEGACY_ORCHESTRATION_DEFINITION_BRAND,
-} from './agent.js';
+} from "./agent.js";
 
 // Errors that are part of the public contract surface
 export {
@@ -61,8 +74,8 @@ export {
   STEP_INPUT_VALIDATION_ERROR_CONTRACT,
   stepInputValidationErrorPayloadSchema,
   isStepInputValidationErrorPayload,
-} from './errors.js';
-export type { StepInputValidationErrorPayload } from './errors.js';
+} from "./errors.js";
+export type { StepInputValidationErrorPayload } from "./errors.js";
 
 // ctx.shared quota — the versioned cross-process size/error contract
 export {
@@ -73,53 +86,68 @@ export {
   findCtxSharedSizeViolation,
   isCtxSharedSizeLimitExceededPayload,
   measureCtxSharedSnapshotBytes,
-} from './ctx-shared-quota.js';
+} from "./ctx-shared-quota.js";
 export type {
   CtxSharedSizeLimitExceededErrorOptions,
   CtxSharedSizeLimitExceededPayload,
   CtxSharedSizeLimitPhase,
   CtxSharedSizeViolation,
-} from './ctx-shared-quota.js';
+} from "./ctx-shared-quota.js";
 
 // ctx.shared serialization — terminal JSON encoding failures at enforcement boundaries
 export {
   CTX_SHARED_SERIALIZATION_ERROR_CONTRACT,
   CtxSharedSerializationError,
   ctxSharedSerializationErrorPayloadSchema,
   isCtxSharedSerializationErrorPayload,
-} from './ctx-shared-serialization.js';
+} from "./ctx-shared-serialization.js";
 export type {
   CtxSharedSerializationErrorOptions,
   CtxSharedSerializationErrorPayload,
   CtxSharedSerializationPhase,
-} from './ctx-shared-serialization.js';
+} from "./ctx-shared-serialization.js";
 
 // Closed platform retry-classification registry.
-export { isNonRetryableStepErrorPayload, parseNonRetryableStepErrorPayload } from './non-retryable-step-error.js';
-export type { NonRetryableStepErrorPayload } from './non-retryable-step-error.js';
+export {
+  isNonRetryableStepErrorPayload,
+  parseNonRetryableStepErrorPayload,
+} from "./non-retryable-step-error.js";
+export type { NonRetryableStepErrorPayload } from "./non-retryable-step-error.js";
 
 // Injected run configuration — the seam a step reads a chosen resource handle
 // from (the entry input the setup panel's settings / resource picker drive).
-export { resolveResourceHandle } from './config.js';
-export type { ResolveResourceHandleOptions } from './config.js';
+export { resolveResourceHandle } from "./config.js";
+export type { ResolveResourceHandleOptions } from "./config.js";
 
 // Introspection — zod→JSON-Schema conversion + step/workflow input contracts.
 // Shared by engine tooling and the build phase (runs outside the engine).
-export { zodToJsonSchema, exampleFromJsonSchema, stepInputContract, workflowInputContract } from './introspection.js';
-export type { StepInputContract, AgentInputContract } from './introspection.js';
+export {
+  zodToJsonSchema,
+  exampleFromJsonSchema,
+  stepInputContract,
+  workflowInputContract,
+} from "./introspection.js";
+export type { StepInputContract, AgentInputContract } from "./introspection.js";
 
 // Manifest types, Zod schema, and generator — the build→engine contract.
-export { MANIFEST_PROTOCOL, agentManifestSchema } from './manifest.js';
-export type { AgentManifest, AgentStepManifest, ManifestTransition } from './manifest.js';
+export { MANIFEST_PROTOCOL, agentManifestSchema } from "./manifest.js";
+export type {
+  AgentManifest,
+  AgentStepManifest,
+  ManifestTransition,
+} from "./manifest.js";
 
 // Multi-agent package inventory — separate from the single-agent build manifest.
-export { PACKAGE_INVENTORY_PROTOCOL, packageInventorySchema } from './package-inventory.js';
+export {
+  PACKAGE_INVENTORY_PROTOCOL,
+  packageInventorySchema,
+} from "./package-inventory.js";
 export type {
   PackageInventory,
   PackageInventoryAgent,
   PackageInventoryIdentityIssue,
   PackageInventoryVersion,
-} from './package-inventory.js';
+} from "./package-inventory.js";
 
 // Package-scoped relationship evidence — separate from identity inventory.
 export {
@@ -131,7 +159,7 @@ export {
   packageGraphEvidenceStaticResultSchema,
   packageGraphRuntimeEvidenceEventSchema,
   projectPackageGraphEvidence,
-} from './package-graph-evidence.js';
+} from "./package-graph-evidence.js";
 export type {
   AppendPackageGraphRuntimeEvidenceEventResult,
   CreatePackageGraphEvidenceStaticResultInput,
@@ -155,8 +183,46 @@ export type {
   PackageGraphRuntimeEvidenceState,
   PackageGraphStaticEvidenceCandidate,
   PackageGraphStaticEvidenceState,
-} from './package-graph-evidence.js';
+} from "./package-graph-evidence.js";
+
+// Package-scoped AgentFacts — factual metadata keyed by inventory agentKey.
+export {
+  PACKAGE_AGENT_FACTS_PROTOCOL,
+  canonicalPackageAgentFactsJson,
+  createPackageAgentFactsSnapshot,
+  packageAgentFactsCardInputSchema,
+  packageAgentFactsCompletenessSchema,
+  packageAgentFactsDiagnosticCodeSchema,
+  packageAgentFactsDiagnosticSchema,
+  packageAgentFactsDirectReferenceSchema,
+  packageAgentFactsEvidenceReferenceSchema,
+  packageAgentFactsProducerSchema,
+  packageAgentFactsRecordSchema,
+  packageAgentFactsSnapshotSchema,
+  packageAgentFactsSourceReferenceSchema,
+} from "./package-agent-facts.js";
+export type {
+  CreatePackageAgentFactsSnapshotInput,
+  PackageAgentFactsCardInput,
+  PackageAgentFactsCapabilityField,
+  PackageAgentFactsCompleteness,
+  PackageAgentFactsDiagnostic,
+  PackageAgentFactsDiagnosticCode,
+  PackageAgentFactsDigest,
+  PackageAgentFactsDirectReference,
+  PackageAgentFactsEvidenceReference,
+  PackageAgentFactsProducer,
+  PackageAgentFactsRecord,
+  PackageAgentFactsSchemaField,
+  PackageAgentFactsSnapshot,
+  PackageAgentFactsSourceReference,
+  PackageAgentFactsStringField,
+} from "./package-agent-facts.js";
 
 // Manifest generator + graph validation — called by the build phase.
-export { buildManifest, validateGraph, assertValidGraph } from './build-manifest.js';
-export type { GraphValidation } from './build-manifest.js';
+export {
+  buildManifest,
+  validateGraph,
+  assertValidGraph,
+} from "./build-manifest.js";
+export type { GraphValidation } from "./build-manifest.js";