@redditech/agent-protocol 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/LICENSE +21 -0
  3. package/README.md +394 -2
  4. package/dist/adl.d.ts +141 -0
  5. package/dist/adl.js +3601 -0
  6. package/dist/agent-stack-fixtures.d.ts +743 -0
  7. package/dist/agent-stack-fixtures.js +1554 -0
  8. package/dist/ai-catalog.d.ts +128 -0
  9. package/dist/ai-catalog.js +373 -0
  10. package/dist/attestation-reputation.d.ts +102 -0
  11. package/dist/attestation-reputation.js +279 -0
  12. package/dist/audd-rail-config.d.ts +102 -0
  13. package/dist/audd-rail-config.js +294 -0
  14. package/dist/browser-wallet-approval.d.ts +293 -0
  15. package/dist/browser-wallet-approval.js +1201 -0
  16. package/dist/discovery-source.d.ts +115 -0
  17. package/dist/discovery-source.js +251 -0
  18. package/dist/evidence-archive.d.ts +73 -0
  19. package/dist/evidence-archive.js +238 -0
  20. package/dist/index.d.ts +23 -0
  21. package/dist/index.js +23 -0
  22. package/dist/mpp-tempo-receipt-shapes.d.ts +201 -0
  23. package/dist/mpp-tempo-receipt-shapes.js +330 -0
  24. package/dist/okf-adapter.d.ts +229 -0
  25. package/dist/okf-adapter.js +556 -0
  26. package/dist/okf-conformance.d.ts +208 -0
  27. package/dist/okf-conformance.js +651 -0
  28. package/dist/okf-instruction-safety.d.ts +192 -0
  29. package/dist/okf-instruction-safety.js +509 -0
  30. package/dist/onboarding-analyser-handoff.d.ts +391 -0
  31. package/dist/onboarding-analyser-handoff.js +959 -0
  32. package/dist/onboarding-state-machine.d.ts +228 -0
  33. package/dist/onboarding-state-machine.js +432 -0
  34. package/dist/payment-records.d.ts +181 -0
  35. package/dist/payment-records.js +599 -0
  36. package/dist/policy.d.ts +33 -0
  37. package/dist/policy.js +45 -0
  38. package/dist/provider-trust.d.ts +113 -0
  39. package/dist/provider-trust.js +346 -0
  40. package/dist/quasar-registry-compatibility.d.ts +113 -0
  41. package/dist/quasar-registry-compatibility.js +214 -0
  42. package/dist/ranking-explainability.d.ts +202 -0
  43. package/dist/ranking-explainability.js +302 -0
  44. package/dist/receipt-v2.d.ts +202 -0
  45. package/dist/receipt-v2.js +418 -0
  46. package/dist/repo-explorer-evidence-manifest.d.ts +387 -0
  47. package/dist/repo-explorer-evidence-manifest.js +1187 -0
  48. package/dist/source-diagnostics.d.ts +84 -0
  49. package/dist/source-diagnostics.js +193 -0
  50. package/dist/source-trust-conformance-matrix.d.ts +207 -0
  51. package/dist/source-trust-conformance-matrix.js +672 -0
  52. package/examples/ard-no-spend-ai-catalog.json +51 -0
  53. package/examples/ard-no-spend-demo.mjs +355 -0
  54. package/examples/interpretation-guide-scenarios.mjs +302 -0
  55. package/package.json +144 -4
@@ -0,0 +1,208 @@
1
+ /**
2
+ * OKF/OpenKB knowledge-bundle conformance diagnostics (#504, epic #468).
3
+ *
4
+ * Deterministic, PURE static-analysis diagnostics that decide whether an
5
+ * OKF-shaped / OpenKB-style knowledge bundle is acceptable as REVIEW/ANALYSIS
6
+ * input for RAP — and nothing more. This module builds directly on the #511
7
+ * adapter spike (`okf-adapter.ts`) and the #503 static fixture corpus
8
+ * (`data/okf-openkb-fixtures/okf-openkb-fixture-corpus.v1.json`): same document
9
+ * roles, trust classifications, and reason-code vocabulary. It does not
10
+ * re-invent either.
11
+ *
12
+ * This module is PURE: no network, no filesystem access, no URL ingestion, no
13
+ * OpenKB install, no LLM/provider call, no MCP/tool call, no script or tool
14
+ * execution, no skill installation, no agent registration, no hosted write,
15
+ * no marketplace publication, no wallet/RPC, no payment activation, no
16
+ * trust/reputation mutation. It only analyses in-memory text the caller
17
+ * already holds. Fail-closed on malformed input and on any request to
18
+ * execute/install/ingest/invoke/generate.
19
+ *
20
+ * ─────────────────────────────────────────────────────────────────────────────
21
+ * REVIEW-ONLY BOUNDARY: a `valid` conformance verdict permits static
22
+ * review/analysis ONLY. It never permits skill installation, agent
23
+ * registration/onboarding, marketplace publication, hosted writes,
24
+ * LLM/provider calls, or execution of any bundle content. Those remain denied
25
+ * regardless of verdict — see `reviewBoundary` on every report.
26
+ * ─────────────────────────────────────────────────────────────────────────────
27
+ *
28
+ * DRAFT/unverified — like the #511 spike, OKF (Open Knowledge Format) is an
29
+ * EXTERNAL format and every OKF-semantic claim below (concept `type`
30
+ * requirement, `index.md`/`log.md` semantics, standard-markdown-link
31
+ * requirement) is illustrative and unconfirmed against the live spec.
32
+ * (DRAFT/unverified — OKF, confirm field semantics before relying on them.)
33
+ */
34
+ import { type OkfDocumentRole, type OkfIndex, type OkfLog, type OkfTrustClassification, type OpenKbDocumentInput } from './okf-adapter.js';
35
+ export declare const OKF_CONFORMANCE_SCHEMA_VERSION: "reddi.okf-conformance.v1";
36
+ /** The OKF semantics this module enforces are unverified against the live external spec. */
37
+ export declare const OKF_CONFORMANCE_IS_DRAFT: true;
38
+ /** Severity vocabulary — aligned with the repo's static-analysis severity vocab
39
+ * (`agent-stack-fixtures.ts` and `okf-adapter.ts` both use info/warning/blocked). */
40
+ export type OkfConformanceSeverity = 'info' | 'warning' | 'blocked';
41
+ /** Deterministic conformance diagnostic codes. Reuses the #511 adapter reason-code
42
+ * vocabulary wherever one exists; adds only index/log expectation codes. */
43
+ export type OkfConformanceCode = 'malformed_frontmatter' | 'concept_type_missing' | 'unsupported_link_syntax' | 'missing_provenance' | 'unknown_frontmatter_preserved' | 'generated_instruction_untrusted' | 'execution_not_allowed' | 'index_missing' | 'log_missing' | 'index_semantics_normalized' | 'log_semantics_normalized' | 'bundle_malformed' | 'document_malformed' | 'operation_not_permitted';
44
+ /**
45
+ * Per-document conformance status — the #504 acceptance-criteria vocabulary:
46
+ * valid, warning, blocked, untrusted_generated_instruction,
47
+ * unsupported_link_syntax, missing_provenance, malformed_frontmatter,
48
+ * execution_not_allowed. The named statuses surface the dominant finding;
49
+ * `valid`/`warning`/`blocked` are the fallbacks by max severity.
50
+ */
51
+ export type OkfConformanceStatus = 'valid' | 'warning' | 'blocked' | 'untrusted_generated_instruction' | 'unsupported_link_syntax' | 'missing_provenance' | 'malformed_frontmatter' | 'execution_not_allowed';
52
+ /** Bundle-level verdict. Even `valid` permits review/analysis only. */
53
+ export type OkfConformanceVerdict = 'valid' | 'warning' | 'blocked';
54
+ /**
55
+ * Explicit unsafe/generated-instruction artifact classes for producer-toolchain
56
+ * output (AGENTS.md, SKILL.md, prompts, scripts, skills, tools, agent
57
+ * definitions). Mirrors the #503 corpus `generatedArtifacts[].artifactKind`
58
+ * vocabulary (`agent_definition`, `skill_definition`, `script`).
59
+ */
60
+ export type OkfGeneratedArtifactClass = 'agent_definition' | 'skill_definition' | 'prompt' | 'script' | 'tool' | 'generated_instruction_other';
61
+ export type OkfConformanceDiagnostic = {
62
+ severity: OkfConformanceSeverity;
63
+ code: OkfConformanceCode;
64
+ /** Document id/path the diagnostic is scoped to, when document-scoped. */
65
+ documentId?: string;
66
+ summary: string;
67
+ action?: string;
68
+ /**
69
+ * For `unsupported_link_syntax`: true when the finding is deterministically
70
+ * adaptable (simple `[[wikilink]]` → standard markdown link, already
71
+ * converted by the #511 adapter); false when it is not (embeds, heading/block
72
+ * refs, empty targets) and must be rewritten at the source.
73
+ */
74
+ adaptable?: boolean;
75
+ /** For generated-instruction / execution findings: the artifact class. */
76
+ artifactClass?: OkfGeneratedArtifactClass;
77
+ };
78
+ export type OkfConformanceDocumentReport = {
79
+ documentId: string;
80
+ documentRole: OkfDocumentRole;
81
+ trustClassification: OkfTrustClassification;
82
+ /** Non-null only for generated-instruction artifacts. */
83
+ artifactClass: OkfGeneratedArtifactClass | null;
84
+ status: OkfConformanceStatus;
85
+ diagnostics: OkfConformanceDiagnostic[];
86
+ };
87
+ /** What a passing (or any) conformance report permits — and permanently denies. */
88
+ export declare const OKF_CONFORMANCE_PERMITTED_USE: readonly ["static_review", "static_analysis", "operator_review_payload", "conformance_reporting"];
89
+ export declare const OKF_CONFORMANCE_DENIED_USE: readonly ["skill_installation", "agent_registration", "agent_onboarding", "marketplace_publication", "hosted_registry_write", "llm_or_provider_call", "script_or_tool_execution", "url_ingestion", "payment_activation", "trust_or_reputation_mutation"];
90
+ export type OkfConformanceReport = {
91
+ schemaVersion: typeof OKF_CONFORMANCE_SCHEMA_VERSION;
92
+ /** OKF-semantic checks are drafted against an unverified external format. */
93
+ draft: true;
94
+ verdict: OkfConformanceVerdict;
95
+ bundleId: string | null;
96
+ documents: OkfConformanceDocumentReport[];
97
+ /** Bundle-level + aggregated per-document diagnostics, in deterministic order. */
98
+ diagnostics: OkfConformanceDiagnostic[];
99
+ /** Deduped codes across all diagnostics. */
100
+ codes: OkfConformanceCode[];
101
+ /** Normalized `index.md` semantics from the #511 adapter, when present. */
102
+ index: OkfIndex | null;
103
+ /** Normalized `log.md` semantics from the #511 adapter, when present. */
104
+ log: OkfLog | null;
105
+ /**
106
+ * REVIEW-ONLY boundary: identical on every report, independent of verdict.
107
+ * Passing conformance permits review/analysis only — never installation,
108
+ * registration, publication, hosted writes, provider calls, or execution.
109
+ */
110
+ reviewBoundary: {
111
+ permittedUse: typeof OKF_CONFORMANCE_PERMITTED_USE;
112
+ deniedUse: typeof OKF_CONFORMANCE_DENIED_USE;
113
+ };
114
+ /** Hard-coded false guardrails — this module never touches any live rail. */
115
+ guardrails: {
116
+ network: false;
117
+ fileSystemRead: false;
118
+ executed: false;
119
+ installed: false;
120
+ urlIngested: false;
121
+ llmInvoked: false;
122
+ mcpInvoked: false;
123
+ skillInstalled: false;
124
+ agentRegistered: false;
125
+ hostedWrite: false;
126
+ marketplacePublished: false;
127
+ paymentActivated: false;
128
+ trustMutated: false;
129
+ instructionsTrusted: false;
130
+ };
131
+ notes: string[];
132
+ };
133
+ /**
134
+ * Input document. Either provide `source` (raw markdown text, optionally
135
+ * starting with a `---` YAML frontmatter fence) or the already-split
136
+ * `frontmatter`/`rawFrontmatter`/`body` fields from the #511 adapter input
137
+ * shape. When `source` is present it wins.
138
+ */
139
+ export type OkfConformanceDocumentInput = OpenKbDocumentInput & {
140
+ source?: string;
141
+ };
142
+ export type OkfConformanceBundleInput = {
143
+ bundleId?: string;
144
+ documents: OkfConformanceDocumentInput[];
145
+ };
146
+ export type OkfConformanceOptions = {
147
+ /** Escalate `missing_provenance` to `blocked` instead of `warning`. */
148
+ requireProvenance?: boolean;
149
+ /** Emit a warning when the bundle has no `index.md`. */
150
+ expectIndex?: boolean;
151
+ /** Emit a warning when the bundle has no `log.md`. */
152
+ expectLog?: boolean;
153
+ /**
154
+ * FAIL-CLOSED: any attempt to execute, install, ingest a URL, invoke an LLM,
155
+ * or generate/install a skill is rejected with `operation_not_permitted`.
156
+ * These flags exist only so requests can be refused deterministically.
157
+ */
158
+ execute?: boolean;
159
+ install?: boolean;
160
+ ingestUrl?: boolean;
161
+ invokeLlm?: boolean;
162
+ generateSkill?: boolean;
163
+ };
164
+ /**
165
+ * Maps the #503 corpus `expectedDiagnostics[].code` vocabulary onto the
166
+ * conformance code vocabulary (which follows the #511 adapter reason codes).
167
+ */
168
+ export declare const OKF_FIXTURE_DIAGNOSTIC_CODE_MAP: {
169
+ readonly unsupported_wikilink_syntax: "unsupported_link_syntax";
170
+ readonly generated_instruction_untrusted: "generated_instruction_untrusted";
171
+ readonly generated_skill_untrusted: "generated_instruction_untrusted";
172
+ readonly script_execution_not_allowed: "execution_not_allowed";
173
+ };
174
+ /** Maps #503 corpus `expectedDiagnostics[].severity` onto acceptable conformance severities. */
175
+ export declare const OKF_FIXTURE_DIAGNOSTIC_SEVERITY_MAP: Record<string, readonly OkfConformanceSeverity[]>;
176
+ /**
177
+ * Builds a conformance bundle input from one fixture of the #503 corpus
178
+ * (`reddi.okf-openkb-fixture-corpus.v1`). Read-only over the fixture object:
179
+ * file previews are consumed as static text and never mutated, so the
180
+ * fixture's `contentSha256` digests are preserved. Fail-closed: a fixture that
181
+ * does not carry a usable `files` array yields an empty-documents input, which
182
+ * `runOkfConformanceDiagnostics` blocks as `bundle_malformed`.
183
+ */
184
+ export declare function conformanceInputFromOkfOpenKbFixture(fixture: unknown): OkfConformanceBundleInput;
185
+ export type OkfParsedDocumentSource = {
186
+ /** Parsed frontmatter object, or undefined when the source has no fence. */
187
+ frontmatter: Record<string, unknown> | undefined;
188
+ body: string;
189
+ diagnostics: OkfConformanceDiagnostic[];
190
+ };
191
+ /**
192
+ * Deterministically splits raw markdown into YAML frontmatter and body.
193
+ * Conservative YAML subset only: `key: value` scalars, `# comments`, and
194
+ * `key:` followed by indented `- item` list lines. Anything else raises
195
+ * `malformed_frontmatter` and is skipped (fail-closed: unparseable content is
196
+ * never trusted). An unterminated fence is also `malformed_frontmatter`; the
197
+ * whole source is then treated as body with no trusted frontmatter.
198
+ */
199
+ export declare function parseOkfDocumentSource(documentId: string, source: string): OkfParsedDocumentSource;
200
+ /**
201
+ * Runs deterministic OKF/OpenKB conformance diagnostics over an in-memory
202
+ * bundle. Pure static analysis: delegates document projection to the #511
203
+ * adapter, then layers the #504 conformance vocabulary (statuses, escalated
204
+ * generated-instruction severities, adaptable-wikilink reporting, index/log
205
+ * expectations, review-only boundary) on top.
206
+ */
207
+ export declare function runOkfConformanceDiagnostics(input: unknown, options?: OkfConformanceOptions): OkfConformanceReport;
208
+ export declare const okfConformanceFixtures: Record<string, OkfConformanceBundleInput>;