@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,192 @@
1
+ /**
2
+ * OKF/OpenKB generated instruction and skill safety review (#505, epic #468).
3
+ *
4
+ * Deterministic, PURE static-analysis safety review for OpenKB/OKF-derived
5
+ * generated instructions, skills, prompts, scripts, tools, and agent
6
+ * definitions. It layers a fixed safety checklist on top of the #504
7
+ * conformance diagnostics (`okf-conformance.ts`, `reddi.okf-conformance.v1`)
8
+ * and REUSES that module's vocabulary — `artifactClass`
9
+ * (agent_definition / skill_definition / prompt / script / tool /
10
+ * generated_instruction_other), severities (info/warning/blocked), the
11
+ * review-only boundary, and the hard-false guardrails — rather than inventing
12
+ * a parallel taxonomy. Trust classification and document roles come from the
13
+ * #511 adapter (`okf-adapter.ts`); fixtures build on the #503 static corpus
14
+ * (`data/okf-openkb-fixtures/okf-openkb-fixture-corpus.v1.json`).
15
+ *
16
+ * REVIEW MODEL — UNTRUSTED BY DEFAULT:
17
+ * Every generated `AGENTS.md`, `SKILL.md`, prompt, script, tool, and
18
+ * agent-definition artifact is untrusted by default. Its disposition is
19
+ * `blocked` even when zero checklist findings fire — content review can never
20
+ * upgrade a generated instruction into a trusted one. Generated instructions
21
+ * MAY be preserved as static evidence/context for operators, but they must
22
+ * NOT be installed, applied, registered, executed, or published without a
23
+ * separate operator-approved issue (see
24
+ * `OKF_GENERATED_ARTIFACT_OPERATOR_GATE`).
25
+ *
26
+ * This module is PURE: no network, no filesystem access, no URL ingestion, no
27
+ * LLM/provider call, no MCP/tool call, no script or tool execution, no skill
28
+ * installation, no agent registration, no hosted write, no marketplace
29
+ * publication, no wallet/RPC, no payment activation, no trust/reputation
30
+ * mutation. All checklist checks are deterministic regular-expression scans
31
+ * over in-memory text the caller already holds. Matched `evidence` snippets
32
+ * are DATA extracted for the operator — never instructions to follow.
33
+ * Fail-closed on malformed input and on any execute/install/ingest/LLM/skill
34
+ * generation request (inherited from the #504 conformance run).
35
+ *
36
+ * DRAFT/unverified — OKF is an EXTERNAL format; OKF-semantic behaviour is
37
+ * inherited from the #504/#511 modules and remains unconfirmed against the
38
+ * live spec. (DRAFT/unverified — OKF, confirm field semantics before relying
39
+ * on them.)
40
+ */
41
+ import { OKF_CONFORMANCE_PERMITTED_USE, OKF_CONFORMANCE_DENIED_USE, type OkfConformanceBundleInput, type OkfConformanceOptions, type OkfConformanceReport, type OkfConformanceSeverity, type OkfGeneratedArtifactClass } from './okf-conformance.js';
42
+ import type { OkfTrustClassification } from './okf-adapter.js';
43
+ export declare const OKF_INSTRUCTION_SAFETY_SCHEMA_VERSION: "reddi.okf-instruction-safety.v1";
44
+ /** Inherits the #504/#511 DRAFT posture: OKF semantics are unverified against the live external spec. */
45
+ export declare const OKF_INSTRUCTION_SAFETY_IS_DRAFT: true;
46
+ /**
47
+ * The #505 safety checklist categories. Deterministic static checks only —
48
+ * every category is a fixed set of regular expressions over document text.
49
+ */
50
+ export type OkfSafetyCheckId = 'prompt_injection' | 'credential_request' | 'tool_expansion' | 'external_call' | 'hidden_instruction' | 'auto_install_or_apply' | 'destructive_command' | 'paid_call_instruction' | 'wallet_rpc_mainnet_instruction' | 'marketplace_publication_claim';
51
+ export type OkfSafetyCheck = {
52
+ id: OkfSafetyCheckId;
53
+ title: string;
54
+ /** What the deterministic patterns look for. */
55
+ description: string;
56
+ /**
57
+ * `always_blocked`: a hit is blocked wherever it appears — such content has
58
+ * no legitimate place in a knowledge bundle.
59
+ * `contextual`: blocked inside generated-instruction artifacts; a warning
60
+ * (needs human review) inside plain documentation, where descriptive
61
+ * mention can be legitimate.
62
+ */
63
+ escalation: 'always_blocked' | 'contextual';
64
+ patterns: readonly RegExp[];
65
+ };
66
+ /**
67
+ * Deterministic pattern sets. All patterns are static and case-insensitive;
68
+ * matched text is surfaced (sanitized + truncated) as operator evidence.
69
+ * Pattern quality note: these are review heuristics for static fixtures, not
70
+ * a bypass-proof filter — the untrusted-by-default rule is what carries the
71
+ * safety guarantee.
72
+ */
73
+ export declare const OKF_SAFETY_CHECKLIST: readonly OkfSafetyCheck[];
74
+ export declare const OKF_SAFETY_CHECK_IDS: readonly OkfSafetyCheckId[];
75
+ /**
76
+ * Operator gate for every generated-instruction artifact: preserved as static
77
+ * evidence/context only. Installation, application, registration, execution,
78
+ * and publication each require a SEPARATE operator-approved issue — never this
79
+ * module, never a passing review.
80
+ */
81
+ export declare const OKF_GENERATED_ARTIFACT_OPERATOR_GATE: {
82
+ readonly mayBePreservedAsEvidence: true;
83
+ readonly installed: false;
84
+ readonly applied: false;
85
+ readonly registered: false;
86
+ readonly executed: false;
87
+ readonly published: false;
88
+ readonly requiresSeparateOperatorApprovedIssue: true;
89
+ };
90
+ /**
91
+ * Per-document safety disposition. There is deliberately NO disposition that
92
+ * grants trust or permits use beyond static review:
93
+ * - `safe_documentation`: plain documentation with zero checklist findings.
94
+ * Still review-only; never instructions.
95
+ * - `needs_human_review`: documentation with contextual findings (external
96
+ * calls, payment/wallet/marketplace mentions, tool expansion) that an
97
+ * operator must judge.
98
+ * - `blocked`: any generated-instruction artifact (untrusted by default,
99
+ * findings or not) and any document with an always-blocked finding.
100
+ */
101
+ export type OkfSafetyDisposition = 'safe_documentation' | 'needs_human_review' | 'blocked';
102
+ /** Bundle verdict: worst per-document disposition, fail-closed on malformed bundles. */
103
+ export type OkfSafetyVerdict = OkfSafetyDisposition;
104
+ export type OkfSafetyFinding = {
105
+ checkId: OkfSafetyCheckId;
106
+ severity: OkfConformanceSeverity;
107
+ documentId: string;
108
+ /** Artifact class of the containing document, when it is a generated artifact. */
109
+ artifactClass?: OkfGeneratedArtifactClass;
110
+ /** Sanitized, truncated matched snippet. DATA for the operator — never an instruction. */
111
+ evidence: string;
112
+ /** Total pattern matches for this check in this document. */
113
+ matchCount: number;
114
+ summary: string;
115
+ action: string;
116
+ };
117
+ export type OkfSafetyDocumentReview = {
118
+ documentId: string;
119
+ trustClassification: OkfTrustClassification;
120
+ /** Non-null only for generated-instruction artifacts (#504 vocabulary). */
121
+ artifactClass: OkfGeneratedArtifactClass | null;
122
+ /** True for every generated artifact — content review never clears it. */
123
+ untrustedByDefault: boolean;
124
+ disposition: OkfSafetyDisposition;
125
+ findings: OkfSafetyFinding[];
126
+ /** Every checklist check runs on every document, in checklist order. */
127
+ checksRun: readonly OkfSafetyCheckId[];
128
+ };
129
+ export type OkfInstructionSafetyReport = {
130
+ schemaVersion: typeof OKF_INSTRUCTION_SAFETY_SCHEMA_VERSION;
131
+ draft: true;
132
+ verdict: OkfSafetyVerdict;
133
+ bundleId: string | null;
134
+ documents: OkfSafetyDocumentReview[];
135
+ /** All findings across documents, in deterministic order. */
136
+ findings: OkfSafetyFinding[];
137
+ /** Deduped checklist categories detected across the bundle. */
138
+ categoriesDetected: OkfSafetyCheckId[];
139
+ /** The full #504 conformance report the review was layered on. */
140
+ conformance: OkfConformanceReport;
141
+ /** Identical review-only boundary as #504 — reused, not redefined. */
142
+ reviewBoundary: {
143
+ permittedUse: typeof OKF_CONFORMANCE_PERMITTED_USE;
144
+ deniedUse: typeof OKF_CONFORMANCE_DENIED_USE;
145
+ };
146
+ /** Generated artifacts: evidence-only preservation; everything else operator-gated. */
147
+ operatorGate: typeof OKF_GENERATED_ARTIFACT_OPERATOR_GATE;
148
+ /** Hard-coded false guardrails — this module never touches any live rail. */
149
+ guardrails: {
150
+ network: false;
151
+ fileSystemRead: false;
152
+ executed: false;
153
+ installed: false;
154
+ applied: false;
155
+ registered: false;
156
+ urlIngested: false;
157
+ llmInvoked: false;
158
+ mcpInvoked: false;
159
+ skillInstalled: false;
160
+ agentRegistered: false;
161
+ hostedWrite: false;
162
+ marketplacePublished: false;
163
+ paymentActivated: false;
164
+ trustMutated: false;
165
+ instructionsTrusted: false;
166
+ };
167
+ notes: string[];
168
+ };
169
+ /** Sanitizes a matched snippet for operator display: escapes zero-width and
170
+ * control characters, collapses newlines, truncates. Evidence is DATA. */
171
+ export declare function sanitizeOkfSafetyEvidence(snippet: string): string;
172
+ /**
173
+ * Runs the full #505 safety checklist over one document's raw text.
174
+ * Deterministic: checks in checklist order, patterns in declaration order; at
175
+ * most one finding per check per document (first match is the evidence,
176
+ * `matchCount` totals all pattern hits). Pure text scanning — the text is
177
+ * never executed, resolved, fetched, or followed.
178
+ */
179
+ export declare function scanOkfSafetyChecklist(documentId: string, text: string, artifactClass?: OkfGeneratedArtifactClass | null): OkfSafetyFinding[];
180
+ export type OkfInstructionSafetyOptions = OkfConformanceOptions;
181
+ /**
182
+ * Runs the #505 generated instruction and skill safety review over an
183
+ * in-memory bundle (same input shape as `runOkfConformanceDiagnostics`).
184
+ * First runs the #504 conformance diagnostics (which classify generated
185
+ * artifacts via `artifactClass` and enforce fail-closed behaviour), then runs
186
+ * the deterministic safety checklist over every document's raw text.
187
+ *
188
+ * UNTRUSTED BY DEFAULT: any document conformance classifies as a generated
189
+ * instruction artifact is `blocked` regardless of checklist findings.
190
+ */
191
+ export declare function runOkfInstructionSafetyReview(input: unknown, options?: OkfInstructionSafetyOptions): OkfInstructionSafetyReport;
192
+ export declare const okfInstructionSafetyFixtures: Record<string, OkfConformanceBundleInput>;