@agentspec/sdk 0.4.0 → 0.5.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 (114) hide show
  1. package/README.md +46 -0
  2. package/dist/evidence-points-C6j4PSsQ.d.cts +1139 -0
  3. package/dist/evidence-points-C6j4PSsQ.d.ts +1139 -0
  4. package/dist/index.cjs +1727 -345
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +1026 -2549
  7. package/dist/index.d.ts +1026 -2549
  8. package/dist/index.js +1678 -344
  9. package/dist/index.js.map +1 -1
  10. package/dist/runtime.cjs +930 -0
  11. package/dist/runtime.cjs.map +1 -0
  12. package/dist/runtime.d.cts +63 -0
  13. package/dist/runtime.d.ts +63 -0
  14. package/dist/runtime.js +921 -0
  15. package/dist/runtime.js.map +1 -0
  16. package/package.json +15 -8
  17. package/schemas/evidence/v1/contract.schema.json +2078 -0
  18. package/schemas/evidence/v1/fixtures/drifted/EvalResult.n-as-string.json +1 -0
  19. package/schemas/evidence/v1/fixtures/drifted/EvalResult.pass-rate-above-one.json +1 -0
  20. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.bad-sha.json +1 -0
  21. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.extra-field.json +1 -0
  22. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.fail-without-reason.json +1 -0
  23. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.missing-ttl.json +1 -0
  24. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.not-verifiable-without-reason.json +1 -0
  25. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.observed-at-epoch.json +1 -0
  26. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.observed-at-out-of-range.json +1 -0
  27. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.observed-at-space-separated.json +1 -0
  28. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.sample-size-boolean.json +1 -0
  29. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.ttl-as-string.json +1 -0
  30. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.unknown-collector.json +1 -0
  31. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.unknown-source.json +1 -0
  32. package/schemas/evidence/v1/fixtures/drifted/Heartbeat.bad-contract-version.json +1 -0
  33. package/schemas/evidence/v1/fixtures/drifted/Heartbeat.bad-record.json +1 -0
  34. package/schemas/evidence/v1/fixtures/drifted/Heartbeat.point-records-over-limit.json +1 -0
  35. package/schemas/evidence/v1/fixtures/drifted/Heartbeat.with-gap.json +1 -0
  36. package/schemas/evidence/v1/fixtures/drifted/ReadinessFinding.bad-severity.json +1 -0
  37. package/schemas/evidence/v1/fixtures/drifted/SidecarPush.missing-sha.json +1 -0
  38. package/schemas/evidence/v1/fixtures/drifted/TrustPolicy.lenient.json +1 -0
  39. package/schemas/evidence/v1/fixtures/valid/EvalResult.live.json +1 -0
  40. package/schemas/evidence/v1/fixtures/valid/EvalResult.null-dataset.json +1 -0
  41. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.fail.json +1 -0
  42. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.null-collector.json +1 -0
  43. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.pass-null-reason.json +1 -0
  44. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.pass.json +1 -0
  45. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.timezone-offset.json +1 -0
  46. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.unknown-reason-code.json +1 -0
  47. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.with-collector.json +1 -0
  48. package/schemas/evidence/v1/fixtures/valid/Heartbeat.contract-null.json +1 -0
  49. package/schemas/evidence/v1/fixtures/valid/Heartbeat.contract-version.json +1 -0
  50. package/schemas/evidence/v1/fixtures/valid/Heartbeat.evidence-points.json +1 -0
  51. package/schemas/evidence/v1/fixtures/valid/Heartbeat.full.json +1 -0
  52. package/schemas/evidence/v1/fixtures/valid/Heartbeat.sdk-no-records.json +1 -0
  53. package/schemas/evidence/v1/fixtures/valid/Heartbeat.sdk.json +1 -0
  54. package/schemas/evidence/v1/fixtures/valid/ReadinessFinding.open-code.json +1 -0
  55. package/schemas/evidence/v1/fixtures/valid/ReadinessFinding.with-subject.json +1 -0
  56. package/schemas/evidence/v1/fixtures/valid/SidecarPush.declared.json +1 -0
  57. package/schemas/evidence/v1/fixtures/valid/TrustPolicy.standard.json +1 -0
  58. package/schemas/evidence/v1/fixtures/valid/TrustPolicy.strict.json +1 -0
  59. package/schemas/grader/v1/fixtures/accepts-fractional-seconds.json +62 -0
  60. package/schemas/grader/v1/fixtures/accepts-leap-day-in-year-below-100.json +62 -0
  61. package/schemas/grader/v1/fixtures/accepts-more-than-6-fractional-digits.json +62 -0
  62. package/schemas/grader/v1/fixtures/accepts-numeric-offset.json +62 -0
  63. package/schemas/grader/v1/fixtures/all-records-must-pass.json +58 -0
  64. package/schemas/grader/v1/fixtures/below-threshold-not-graded.json +61 -0
  65. package/schemas/grader/v1/fixtures/derived-rule-fails-when-a-parent-fails.json +67 -0
  66. package/schemas/grader/v1/fixtures/derived-rule-follows-memory-write-parent.json +43 -0
  67. package/schemas/grader/v1/fixtures/derived-rule-passes-with-its-parents.json +64 -0
  68. package/schemas/grader/v1/fixtures/derived-rule-unverified-when-a-parent-has-no-evidence.json +51 -0
  69. package/schemas/grader/v1/fixtures/expired-record-is-stale.json +66 -0
  70. package/schemas/grader/v1/fixtures/fail-beats-not-verifiable.json +62 -0
  71. package/schemas/grader/v1/fixtures/grade-band-b.json +62 -0
  72. package/schemas/grader/v1/fixtures/independent-from-listed-collector-is-admitted.json +39 -0
  73. package/schemas/grader/v1/fixtures/independent-from-unlisted-collector-is-rejected.json +47 -0
  74. package/schemas/grader/v1/fixtures/low-severity-coverage-only.json +90 -0
  75. package/schemas/grader/v1/fixtures/malformed-point-is-ignored.json +67 -0
  76. package/schemas/grader/v1/fixtures/never-admitted-sources-standard.json +196 -0
  77. package/schemas/grader/v1/fixtures/never-admitted-sources-strict.json +196 -0
  78. package/schemas/grader/v1/fixtures/not-admitted-outranks-mismatch.json +64 -0
  79. package/schemas/grader/v1/fixtures/not-verifiable-ignored-when-one-passes.json +58 -0
  80. package/schemas/grader/v1/fixtures/not-verifiable-only-keeps-reason.json +71 -0
  81. package/schemas/grader/v1/fixtures/not-wired-point-drops-a-fail-when-no-point-of-the-rule-is-wired.json +59 -0
  82. package/schemas/grader/v1/fixtures/not-wired-point-drops-a-wired-point-pass.json +87 -0
  83. package/schemas/grader/v1/fixtures/not-wired-point-drops-its-own-earlier-fail-when-another-point-is-wired.json +70 -0
  84. package/schemas/grader/v1/fixtures/not-wired-point-ignores-a-wired-point-fail-without-the-rule-id.json +69 -0
  85. package/schemas/grader/v1/fixtures/not-wired-point-keeps-a-wired-point-fail.json +79 -0
  86. package/schemas/grader/v1/fixtures/not-wired-point-keeps-independent-evidence.json +64 -0
  87. package/schemas/grader/v1/fixtures/not-wired-point-never-passes.json +107 -0
  88. package/schemas/grader/v1/fixtures/offline-record-is-not-admitted-yet.json +47 -0
  89. package/schemas/grader/v1/fixtures/record-without-collector-is-admitted-until-producers-set-it.json +38 -0
  90. package/schemas/grader/v1/fixtures/records-without-rule-id-never-graded.json +62 -0
  91. package/schemas/grader/v1/fixtures/rejects-compact-timestamp.json +56 -0
  92. package/schemas/grader/v1/fixtures/rejects-hour-24-lowercase-separator.json +56 -0
  93. package/schemas/grader/v1/fixtures/rejects-hour-24-space-separator.json +56 -0
  94. package/schemas/grader/v1/fixtures/rejects-hour-24.json +56 -0
  95. package/schemas/grader/v1/fixtures/rejects-impossible-date-feb-29.json +56 -0
  96. package/schemas/grader/v1/fixtures/rejects-lowercase-t.json +56 -0
  97. package/schemas/grader/v1/fixtures/rejects-lowercase-z.json +56 -0
  98. package/schemas/grader/v1/fixtures/rejects-offset-hours-above-23.json +56 -0
  99. package/schemas/grader/v1/fixtures/rejects-offset-minutes-above-59.json +56 -0
  100. package/schemas/grader/v1/fixtures/rejects-offsetless-timestamp.json +56 -0
  101. package/schemas/grader/v1/fixtures/rejects-space-separator.json +56 -0
  102. package/schemas/grader/v1/fixtures/rejects-year-zero.json +56 -0
  103. package/schemas/grader/v1/fixtures/rounds-coverage-before-the-threshold.json +850 -0
  104. package/schemas/grader/v1/fixtures/rounds-verified-before-the-band.json +674 -0
  105. package/schemas/grader/v1/fixtures/sdk-observed-from-evidence-point-rule-is-admitted-standard.json +39 -0
  106. package/schemas/grader/v1/fixtures/sdk-observed-from-evidence-point-rule-is-not-admitted-strict.json +47 -0
  107. package/schemas/grader/v1/fixtures/sdk-observed-standard.json +58 -0
  108. package/schemas/grader/v1/fixtures/sdk-observed-strict.json +66 -0
  109. package/schemas/grader/v1/fixtures/sdk-observed-without-evidence-point-source-is-rejected.json +47 -0
  110. package/schemas/grader/v1/fixtures/sdk-only-agent-all-points-fired.json +116 -0
  111. package/schemas/grader/v1/fixtures/stale-outranks-mismatch.json +64 -0
  112. package/schemas/grader/v1/fixtures/strict-admits-independent.json +39 -0
  113. package/schemas/grader/v1/fixtures/sub-millisecond-expiry-boundary.json +38 -0
  114. package/schemas/v1/agent.schema.json +372 -198
package/README.md ADDED
@@ -0,0 +1,46 @@
1
+ # @agentspec/sdk
2
+
3
+ TypeScript SDK for [AgentSpec](https://github.com/agents-oss/agentspec): the `agent.yaml` schema, loader, health checks, audit rules and reporter, plus the TypeScript runtime SDK for agents.
4
+
5
+ ```bash
6
+ npm install @agentspec/sdk
7
+ ```
8
+
9
+ ## Two entry points
10
+
11
+ | Import | For | Holds |
12
+ |---|---|---|
13
+ | `@agentspec/sdk` | Tools and agents | `loadManifest`, `ManifestSchema`, `runHealthCheck`, `runAudit`, `CONTRACT`, `AgentSpecReporter` (health report and push mode) |
14
+ | `@agentspec/sdk/runtime` | Agent code | The evidence points of ADR-0039; no framework, OpenTelemetry or audit-engine import |
15
+
16
+ ## Evidence points
17
+
18
+ Create the reporter, then wrap the operations the rules are about. The Python SDK (`agentspec-sdk`, imported as `agentspec_sdk`) has the same evidence points and record shapes.
19
+
20
+ ```typescript
21
+ import * as yaml from 'js-yaml'
22
+ import { AgentSpecReporter, loadManifest } from '@agentspec/sdk'
23
+ import { guardrail, tool } from '@agentspec/sdk/runtime'
24
+
25
+ const { manifest, raw, baseDir } = loadManifest('agent.yaml')
26
+ const reporter = new AgentSpecReporter(manifest, {
27
+ baseDir,
28
+ rawManifest: yaml.load(raw, { schema: yaml.JSON_SCHEMA }) as Record<string, unknown>,
29
+ })
30
+
31
+ const checkInput = guardrail((text: string) => text, { type: 'prompt-injection', direction: 'input' }) // SEC-LLM-01
32
+ const searchWeb = tool(async (query: string) => [] as string[], { name: 'search-web' }) // TOOL-01
33
+
34
+ reporter.startPushMode({ apiKey: '<agent token>' }) // heartbeat with each evidence point's state and records
35
+ ```
36
+
37
+ | Helper | Contract name | Wraps |
38
+ |---|---|---|
39
+ | `guardrail(fn, { type, direction })` | `guardrail` | A guardrail function |
40
+ | `tool(fn, { name })` | `tool` | A local tool function |
41
+ | `mcpClient(client, { server })` | `mcpClient` | A stdio MCP client |
42
+ | `memoryWrite(backend)` | `memoryWrite` | A LangGraph checkpointer or Store: scrubs, applies the TTL, audits |
43
+ | `vectorStore(client, { namespace })` | `vectorStore` | A vector store client |
44
+ | `structuredLogging({ name })` | `logging` | Returns a logger whose lines are JSON |
45
+
46
+ Each applicable evidence point is reported `fired`, `wired` or `not_wired`; `not_wired` never passes. See the [runtime SDK concept page](../../docs/concepts/runtime-sdk.md) and the [evidence wiring guide](../../docs/guides/wire-evidence-points.md).