@agentspec/sdk 0.2.2 → 0.2.4

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.
package/dist/index.d.cts CHANGED
@@ -690,7 +690,7 @@ declare const ObservabilitySchema: z.ZodObject<{
690
690
  } | undefined;
691
691
  }>;
692
692
  declare const ComplianceSchema: z.ZodObject<{
693
- packs: z.ZodOptional<z.ZodArray<z.ZodEnum<["owasp-llm-top10", "memory-hygiene", "model-resilience", "evaluation-coverage", "observability"]>, "many">>;
693
+ packs: z.ZodOptional<z.ZodArray<z.ZodEnum<["owasp-llm-top10", "memory-hygiene", "model-resilience", "evaluation-coverage", "observability", "metadata-quality"]>, "many">>;
694
694
  suppressions: z.ZodOptional<z.ZodArray<z.ZodObject<{
695
695
  rule: z.ZodString;
696
696
  reason: z.ZodString;
@@ -709,7 +709,7 @@ declare const ComplianceSchema: z.ZodObject<{
709
709
  }>, "many">>;
710
710
  auditSchedule: z.ZodOptional<z.ZodEnum<["daily", "weekly", "monthly", "on-change"]>>;
711
711
  }, "strip", z.ZodTypeAny, {
712
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
712
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
713
713
  suppressions?: {
714
714
  rule: string;
715
715
  reason: string;
@@ -718,7 +718,7 @@ declare const ComplianceSchema: z.ZodObject<{
718
718
  }[] | undefined;
719
719
  auditSchedule?: "daily" | "weekly" | "monthly" | "on-change" | undefined;
720
720
  }, {
721
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
721
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
722
722
  suppressions?: {
723
723
  rule: string;
724
724
  reason: string;
@@ -1712,7 +1712,7 @@ declare const ManifestSchema: z.ZodObject<{
1712
1712
  } | undefined;
1713
1713
  }>>;
1714
1714
  compliance: z.ZodOptional<z.ZodObject<{
1715
- packs: z.ZodOptional<z.ZodArray<z.ZodEnum<["owasp-llm-top10", "memory-hygiene", "model-resilience", "evaluation-coverage", "observability"]>, "many">>;
1715
+ packs: z.ZodOptional<z.ZodArray<z.ZodEnum<["owasp-llm-top10", "memory-hygiene", "model-resilience", "evaluation-coverage", "observability", "metadata-quality"]>, "many">>;
1716
1716
  suppressions: z.ZodOptional<z.ZodArray<z.ZodObject<{
1717
1717
  rule: z.ZodString;
1718
1718
  reason: z.ZodString;
@@ -1731,7 +1731,7 @@ declare const ManifestSchema: z.ZodObject<{
1731
1731
  }>, "many">>;
1732
1732
  auditSchedule: z.ZodOptional<z.ZodEnum<["daily", "weekly", "monthly", "on-change"]>>;
1733
1733
  }, "strip", z.ZodTypeAny, {
1734
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
1734
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
1735
1735
  suppressions?: {
1736
1736
  rule: string;
1737
1737
  reason: string;
@@ -1740,7 +1740,7 @@ declare const ManifestSchema: z.ZodObject<{
1740
1740
  }[] | undefined;
1741
1741
  auditSchedule?: "daily" | "weekly" | "monthly" | "on-change" | undefined;
1742
1742
  }, {
1743
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
1743
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
1744
1744
  suppressions?: {
1745
1745
  rule: string;
1746
1746
  reason: string;
@@ -1996,7 +1996,7 @@ declare const ManifestSchema: z.ZodObject<{
1996
1996
  thresholds?: Record<string, number> | undefined;
1997
1997
  } | undefined;
1998
1998
  compliance?: {
1999
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
1999
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
2000
2000
  suppressions?: {
2001
2001
  rule: string;
2002
2002
  reason: string;
@@ -2228,7 +2228,7 @@ declare const ManifestSchema: z.ZodObject<{
2228
2228
  ciGate?: boolean | undefined;
2229
2229
  } | undefined;
2230
2230
  compliance?: {
2231
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
2231
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
2232
2232
  suppressions?: {
2233
2233
  rule: string;
2234
2234
  reason: string;
@@ -2472,7 +2472,7 @@ declare const ManifestSchema: z.ZodObject<{
2472
2472
  thresholds?: Record<string, number> | undefined;
2473
2473
  } | undefined;
2474
2474
  compliance?: {
2475
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
2475
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
2476
2476
  suppressions?: {
2477
2477
  rule: string;
2478
2478
  reason: string;
@@ -2716,7 +2716,7 @@ declare const ManifestSchema: z.ZodObject<{
2716
2716
  ciGate?: boolean | undefined;
2717
2717
  } | undefined;
2718
2718
  compliance?: {
2719
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
2719
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
2720
2720
  suppressions?: {
2721
2721
  rule: string;
2722
2722
  reason: string;
@@ -2892,7 +2892,7 @@ declare function runHealthCheck(manifest: AgentSpecManifest, opts?: HealthCheckO
2892
2892
  type RuleSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
2893
2893
  /** Canonical severity type shared across packages. Alias of RuleSeverity. */
2894
2894
  type Severity = RuleSeverity;
2895
- type CompliancePack = 'owasp-llm-top10' | 'model-resilience' | 'memory-hygiene' | 'evaluation-coverage' | 'observability';
2895
+ type CompliancePack = 'owasp-llm-top10' | 'model-resilience' | 'memory-hygiene' | 'evaluation-coverage' | 'observability' | 'metadata-quality';
2896
2896
  type EvidenceLevel = 'declarative' | 'probed' | 'behavioral' | 'external';
2897
2897
  interface RuleResult {
2898
2898
  pass: boolean;
@@ -3058,6 +3058,38 @@ interface PushModeOptions {
3058
3058
  onError?: (err: Error) => void;
3059
3059
  }
3060
3060
 
3061
+ /** In-process token usage counter — aggregates LLM call tokens between heartbeat pushes. */
3062
+ interface ModelUsageEntry {
3063
+ modelId: string;
3064
+ promptTokens: number;
3065
+ completionTokens: number;
3066
+ totalTokens: number;
3067
+ callCount: number;
3068
+ }
3069
+ interface UsageSnapshot {
3070
+ windowStartedAt: string;
3071
+ models: ModelUsageEntry[];
3072
+ totalTokens: number;
3073
+ totalCalls: number;
3074
+ }
3075
+ declare class UsageLedger {
3076
+ private counters;
3077
+ private windowStart;
3078
+ /**
3079
+ * Record token usage for a single LLM call.
3080
+ * Call this once per LLM invocation with the model ID and token counts.
3081
+ */
3082
+ record(modelId: string, promptTokens: number, completionTokens: number): void;
3083
+ /**
3084
+ * Return a frozen snapshot of the current usage window.
3085
+ *
3086
+ * @param reset - When true (default), clears all counters and starts a new
3087
+ * window. Use reset=true in the heartbeat push so each window is shipped
3088
+ * exactly once. Use reset=false for inspection without draining.
3089
+ */
3090
+ snapshot(reset?: boolean): UsageSnapshot;
3091
+ }
3092
+
3061
3093
  /**
3062
3094
  * AgentSpecReporter — agent-side SDK module.
3063
3095
  *
@@ -3101,6 +3133,8 @@ declare class AgentSpecReporter {
3101
3133
  private refreshing;
3102
3134
  private stopped;
3103
3135
  private readonly registeredTools;
3136
+ /** In-process token usage accumulator. */
3137
+ readonly usage: UsageLedger;
3104
3138
  constructor(manifest: AgentSpecManifest, opts?: ReporterOptions);
3105
3139
  /**
3106
3140
  * Register a tool handler by name.
@@ -3191,7 +3225,7 @@ declare function agentSpecFastifyPlugin(reporter: AgentSpecReporter): FastifyPlu
3191
3225
  * Express middleware adapter for AgentSpecReporter.
3192
3226
  *
3193
3227
  * Returns a plain Express middleware (req, res, next) that handles
3194
- * GET /health relative to the mount point.
3228
+ * GET /health and GET /usage relative to the mount point.
3195
3229
  *
3196
3230
  * Usage:
3197
3231
  * import { AgentSpecReporter } from '@agentspec/sdk'
@@ -3240,8 +3274,9 @@ declare function agentSpecExpressRouter(reporter: AgentSpecReporter): ExpressMid
3240
3274
  * the check returns 'skip' rather than 'fail' (the env check will surface the
3241
3275
  * underlying problem).
3242
3276
  *
3243
- * Security: link-local (169.254.x.x) and loopback (127.x.x.x, ::1) addresses
3244
- * are always rejected to prevent unintentional SSRF in container deployments.
3277
+ * Security: link-local (169.254.x.x), loopback (127.x.x.x, ::1), and RFC 1918 private
3278
+ * address ranges (10.x, 172.16-31.x, 192.168.x) are always rejected to prevent
3279
+ * unintentional SSRF in container deployments.
3245
3280
  */
3246
3281
 
3247
3282
  interface ServiceSpec {
@@ -3254,4 +3289,4 @@ interface ServiceSpec {
3254
3289
  */
3255
3290
  declare function runServiceChecks(services: ServiceSpec[]): Promise<HealthCheck[]>;
3256
3291
 
3257
- export { AUDIT_RULE_IDS, type AgentSpecChatEndpoint, type AgentSpecCompliance, type AgentSpecEvaluation, type AgentSpecGuardrails, type AgentSpecHumanInTheLoop, type AgentSpecManifest, type AgentSpecMcpServer, type AgentSpecMemory, type AgentSpecMetadata, type AgentSpecModel, type AgentSpecObservability, type AgentSpecPrompts, AgentSpecReporter, type AgentSpecRequires, type AgentSpecTool, type AuditOptions, type AuditReport, type AuditRule, type AuditViolation, type CheckSeverity, type CheckStatus, type CompliancePack, type EvidenceBreakdown, type EvidenceLevel, type FrameworkAdapter, type GeneratedAgent, type HealthCheck, type HealthCheckOptions, type HealthReport, type HealthStatus, LATEST_API_VERSION, type LoadOptions, ManifestSchema, type Migration, type ParsedManifest, type ProofRecord, type PushModeOptions, type RefType, type ReporterOptions, type ResolverOptions, type RuleResult, type RuleSeverity, type SecretBackend, type Severity, type SuppressionRecord, agentSpecExpressRouter, agentSpecFastifyPlugin, collectEnvRefs, collectFileRefs, detectRefType, detectVersion, exportJsonSchema, generateAdapter, getAdapter, isLatestVersion, isProofRecord, listAdapters, loadManifest, migrateManifest, registerAdapter, resolveRef, resolveRefs, runAudit, runHealthCheck, runServiceChecks, scoreToGrade, tryLoadManifest };
3292
+ export { AUDIT_RULE_IDS, type AgentSpecChatEndpoint, type AgentSpecCompliance, type AgentSpecEvaluation, type AgentSpecGuardrails, type AgentSpecHumanInTheLoop, type AgentSpecManifest, type AgentSpecMcpServer, type AgentSpecMemory, type AgentSpecMetadata, type AgentSpecModel, type AgentSpecObservability, type AgentSpecPrompts, AgentSpecReporter, type AgentSpecRequires, type AgentSpecTool, type AuditOptions, type AuditReport, type AuditRule, type AuditViolation, type CheckSeverity, type CheckStatus, type CompliancePack, type EvidenceBreakdown, type EvidenceLevel, type FrameworkAdapter, type GeneratedAgent, type HealthCheck, type HealthCheckOptions, type HealthReport, type HealthStatus, LATEST_API_VERSION, type LoadOptions, ManifestSchema, type Migration, type ModelUsageEntry, type ParsedManifest, type ProofRecord, type PushModeOptions, type RefType, type ReporterOptions, type ResolverOptions, type RuleResult, type RuleSeverity, type SecretBackend, type Severity, type SuppressionRecord, UsageLedger, type UsageSnapshot, agentSpecExpressRouter, agentSpecFastifyPlugin, collectEnvRefs, collectFileRefs, detectRefType, detectVersion, exportJsonSchema, generateAdapter, getAdapter, isLatestVersion, isProofRecord, listAdapters, loadManifest, migrateManifest, registerAdapter, resolveRef, resolveRefs, runAudit, runHealthCheck, runServiceChecks, scoreToGrade, tryLoadManifest };
package/dist/index.d.ts CHANGED
@@ -690,7 +690,7 @@ declare const ObservabilitySchema: z.ZodObject<{
690
690
  } | undefined;
691
691
  }>;
692
692
  declare const ComplianceSchema: z.ZodObject<{
693
- packs: z.ZodOptional<z.ZodArray<z.ZodEnum<["owasp-llm-top10", "memory-hygiene", "model-resilience", "evaluation-coverage", "observability"]>, "many">>;
693
+ packs: z.ZodOptional<z.ZodArray<z.ZodEnum<["owasp-llm-top10", "memory-hygiene", "model-resilience", "evaluation-coverage", "observability", "metadata-quality"]>, "many">>;
694
694
  suppressions: z.ZodOptional<z.ZodArray<z.ZodObject<{
695
695
  rule: z.ZodString;
696
696
  reason: z.ZodString;
@@ -709,7 +709,7 @@ declare const ComplianceSchema: z.ZodObject<{
709
709
  }>, "many">>;
710
710
  auditSchedule: z.ZodOptional<z.ZodEnum<["daily", "weekly", "monthly", "on-change"]>>;
711
711
  }, "strip", z.ZodTypeAny, {
712
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
712
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
713
713
  suppressions?: {
714
714
  rule: string;
715
715
  reason: string;
@@ -718,7 +718,7 @@ declare const ComplianceSchema: z.ZodObject<{
718
718
  }[] | undefined;
719
719
  auditSchedule?: "daily" | "weekly" | "monthly" | "on-change" | undefined;
720
720
  }, {
721
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
721
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
722
722
  suppressions?: {
723
723
  rule: string;
724
724
  reason: string;
@@ -1712,7 +1712,7 @@ declare const ManifestSchema: z.ZodObject<{
1712
1712
  } | undefined;
1713
1713
  }>>;
1714
1714
  compliance: z.ZodOptional<z.ZodObject<{
1715
- packs: z.ZodOptional<z.ZodArray<z.ZodEnum<["owasp-llm-top10", "memory-hygiene", "model-resilience", "evaluation-coverage", "observability"]>, "many">>;
1715
+ packs: z.ZodOptional<z.ZodArray<z.ZodEnum<["owasp-llm-top10", "memory-hygiene", "model-resilience", "evaluation-coverage", "observability", "metadata-quality"]>, "many">>;
1716
1716
  suppressions: z.ZodOptional<z.ZodArray<z.ZodObject<{
1717
1717
  rule: z.ZodString;
1718
1718
  reason: z.ZodString;
@@ -1731,7 +1731,7 @@ declare const ManifestSchema: z.ZodObject<{
1731
1731
  }>, "many">>;
1732
1732
  auditSchedule: z.ZodOptional<z.ZodEnum<["daily", "weekly", "monthly", "on-change"]>>;
1733
1733
  }, "strip", z.ZodTypeAny, {
1734
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
1734
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
1735
1735
  suppressions?: {
1736
1736
  rule: string;
1737
1737
  reason: string;
@@ -1740,7 +1740,7 @@ declare const ManifestSchema: z.ZodObject<{
1740
1740
  }[] | undefined;
1741
1741
  auditSchedule?: "daily" | "weekly" | "monthly" | "on-change" | undefined;
1742
1742
  }, {
1743
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
1743
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
1744
1744
  suppressions?: {
1745
1745
  rule: string;
1746
1746
  reason: string;
@@ -1996,7 +1996,7 @@ declare const ManifestSchema: z.ZodObject<{
1996
1996
  thresholds?: Record<string, number> | undefined;
1997
1997
  } | undefined;
1998
1998
  compliance?: {
1999
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
1999
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
2000
2000
  suppressions?: {
2001
2001
  rule: string;
2002
2002
  reason: string;
@@ -2228,7 +2228,7 @@ declare const ManifestSchema: z.ZodObject<{
2228
2228
  ciGate?: boolean | undefined;
2229
2229
  } | undefined;
2230
2230
  compliance?: {
2231
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
2231
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
2232
2232
  suppressions?: {
2233
2233
  rule: string;
2234
2234
  reason: string;
@@ -2472,7 +2472,7 @@ declare const ManifestSchema: z.ZodObject<{
2472
2472
  thresholds?: Record<string, number> | undefined;
2473
2473
  } | undefined;
2474
2474
  compliance?: {
2475
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
2475
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
2476
2476
  suppressions?: {
2477
2477
  rule: string;
2478
2478
  reason: string;
@@ -2716,7 +2716,7 @@ declare const ManifestSchema: z.ZodObject<{
2716
2716
  ciGate?: boolean | undefined;
2717
2717
  } | undefined;
2718
2718
  compliance?: {
2719
- packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability")[] | undefined;
2719
+ packs?: ("owasp-llm-top10" | "memory-hygiene" | "model-resilience" | "evaluation-coverage" | "observability" | "metadata-quality")[] | undefined;
2720
2720
  suppressions?: {
2721
2721
  rule: string;
2722
2722
  reason: string;
@@ -2892,7 +2892,7 @@ declare function runHealthCheck(manifest: AgentSpecManifest, opts?: HealthCheckO
2892
2892
  type RuleSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
2893
2893
  /** Canonical severity type shared across packages. Alias of RuleSeverity. */
2894
2894
  type Severity = RuleSeverity;
2895
- type CompliancePack = 'owasp-llm-top10' | 'model-resilience' | 'memory-hygiene' | 'evaluation-coverage' | 'observability';
2895
+ type CompliancePack = 'owasp-llm-top10' | 'model-resilience' | 'memory-hygiene' | 'evaluation-coverage' | 'observability' | 'metadata-quality';
2896
2896
  type EvidenceLevel = 'declarative' | 'probed' | 'behavioral' | 'external';
2897
2897
  interface RuleResult {
2898
2898
  pass: boolean;
@@ -3058,6 +3058,38 @@ interface PushModeOptions {
3058
3058
  onError?: (err: Error) => void;
3059
3059
  }
3060
3060
 
3061
+ /** In-process token usage counter — aggregates LLM call tokens between heartbeat pushes. */
3062
+ interface ModelUsageEntry {
3063
+ modelId: string;
3064
+ promptTokens: number;
3065
+ completionTokens: number;
3066
+ totalTokens: number;
3067
+ callCount: number;
3068
+ }
3069
+ interface UsageSnapshot {
3070
+ windowStartedAt: string;
3071
+ models: ModelUsageEntry[];
3072
+ totalTokens: number;
3073
+ totalCalls: number;
3074
+ }
3075
+ declare class UsageLedger {
3076
+ private counters;
3077
+ private windowStart;
3078
+ /**
3079
+ * Record token usage for a single LLM call.
3080
+ * Call this once per LLM invocation with the model ID and token counts.
3081
+ */
3082
+ record(modelId: string, promptTokens: number, completionTokens: number): void;
3083
+ /**
3084
+ * Return a frozen snapshot of the current usage window.
3085
+ *
3086
+ * @param reset - When true (default), clears all counters and starts a new
3087
+ * window. Use reset=true in the heartbeat push so each window is shipped
3088
+ * exactly once. Use reset=false for inspection without draining.
3089
+ */
3090
+ snapshot(reset?: boolean): UsageSnapshot;
3091
+ }
3092
+
3061
3093
  /**
3062
3094
  * AgentSpecReporter — agent-side SDK module.
3063
3095
  *
@@ -3101,6 +3133,8 @@ declare class AgentSpecReporter {
3101
3133
  private refreshing;
3102
3134
  private stopped;
3103
3135
  private readonly registeredTools;
3136
+ /** In-process token usage accumulator. */
3137
+ readonly usage: UsageLedger;
3104
3138
  constructor(manifest: AgentSpecManifest, opts?: ReporterOptions);
3105
3139
  /**
3106
3140
  * Register a tool handler by name.
@@ -3191,7 +3225,7 @@ declare function agentSpecFastifyPlugin(reporter: AgentSpecReporter): FastifyPlu
3191
3225
  * Express middleware adapter for AgentSpecReporter.
3192
3226
  *
3193
3227
  * Returns a plain Express middleware (req, res, next) that handles
3194
- * GET /health relative to the mount point.
3228
+ * GET /health and GET /usage relative to the mount point.
3195
3229
  *
3196
3230
  * Usage:
3197
3231
  * import { AgentSpecReporter } from '@agentspec/sdk'
@@ -3240,8 +3274,9 @@ declare function agentSpecExpressRouter(reporter: AgentSpecReporter): ExpressMid
3240
3274
  * the check returns 'skip' rather than 'fail' (the env check will surface the
3241
3275
  * underlying problem).
3242
3276
  *
3243
- * Security: link-local (169.254.x.x) and loopback (127.x.x.x, ::1) addresses
3244
- * are always rejected to prevent unintentional SSRF in container deployments.
3277
+ * Security: link-local (169.254.x.x), loopback (127.x.x.x, ::1), and RFC 1918 private
3278
+ * address ranges (10.x, 172.16-31.x, 192.168.x) are always rejected to prevent
3279
+ * unintentional SSRF in container deployments.
3245
3280
  */
3246
3281
 
3247
3282
  interface ServiceSpec {
@@ -3254,4 +3289,4 @@ interface ServiceSpec {
3254
3289
  */
3255
3290
  declare function runServiceChecks(services: ServiceSpec[]): Promise<HealthCheck[]>;
3256
3291
 
3257
- export { AUDIT_RULE_IDS, type AgentSpecChatEndpoint, type AgentSpecCompliance, type AgentSpecEvaluation, type AgentSpecGuardrails, type AgentSpecHumanInTheLoop, type AgentSpecManifest, type AgentSpecMcpServer, type AgentSpecMemory, type AgentSpecMetadata, type AgentSpecModel, type AgentSpecObservability, type AgentSpecPrompts, AgentSpecReporter, type AgentSpecRequires, type AgentSpecTool, type AuditOptions, type AuditReport, type AuditRule, type AuditViolation, type CheckSeverity, type CheckStatus, type CompliancePack, type EvidenceBreakdown, type EvidenceLevel, type FrameworkAdapter, type GeneratedAgent, type HealthCheck, type HealthCheckOptions, type HealthReport, type HealthStatus, LATEST_API_VERSION, type LoadOptions, ManifestSchema, type Migration, type ParsedManifest, type ProofRecord, type PushModeOptions, type RefType, type ReporterOptions, type ResolverOptions, type RuleResult, type RuleSeverity, type SecretBackend, type Severity, type SuppressionRecord, agentSpecExpressRouter, agentSpecFastifyPlugin, collectEnvRefs, collectFileRefs, detectRefType, detectVersion, exportJsonSchema, generateAdapter, getAdapter, isLatestVersion, isProofRecord, listAdapters, loadManifest, migrateManifest, registerAdapter, resolveRef, resolveRefs, runAudit, runHealthCheck, runServiceChecks, scoreToGrade, tryLoadManifest };
3292
+ export { AUDIT_RULE_IDS, type AgentSpecChatEndpoint, type AgentSpecCompliance, type AgentSpecEvaluation, type AgentSpecGuardrails, type AgentSpecHumanInTheLoop, type AgentSpecManifest, type AgentSpecMcpServer, type AgentSpecMemory, type AgentSpecMetadata, type AgentSpecModel, type AgentSpecObservability, type AgentSpecPrompts, AgentSpecReporter, type AgentSpecRequires, type AgentSpecTool, type AuditOptions, type AuditReport, type AuditRule, type AuditViolation, type CheckSeverity, type CheckStatus, type CompliancePack, type EvidenceBreakdown, type EvidenceLevel, type FrameworkAdapter, type GeneratedAgent, type HealthCheck, type HealthCheckOptions, type HealthReport, type HealthStatus, LATEST_API_VERSION, type LoadOptions, ManifestSchema, type Migration, type ModelUsageEntry, type ParsedManifest, type ProofRecord, type PushModeOptions, type RefType, type ReporterOptions, type ResolverOptions, type RuleResult, type RuleSeverity, type SecretBackend, type Severity, type SuppressionRecord, UsageLedger, type UsageSnapshot, agentSpecExpressRouter, agentSpecFastifyPlugin, collectEnvRefs, collectFileRefs, detectRefType, detectVersion, exportJsonSchema, generateAdapter, getAdapter, isLatestVersion, isProofRecord, listAdapters, loadManifest, migrateManifest, registerAdapter, resolveRef, resolveRefs, runAudit, runHealthCheck, runServiceChecks, scoreToGrade, tryLoadManifest };
package/dist/index.js CHANGED
@@ -3,6 +3,7 @@ import { zodToJsonSchema } from 'zod-to-json-schema';
3
3
  import { readFileSync, existsSync } from 'fs';
4
4
  import { resolve, sep, dirname } from 'path';
5
5
  import yaml from 'js-yaml';
6
+ import { isIP } from 'net';
6
7
 
7
8
  // src/schema/manifest.schema.ts
8
9
  var refOrLiteral = z.string();
@@ -294,7 +295,8 @@ var ComplianceSchema = z.object({
294
295
  "memory-hygiene",
295
296
  "model-resilience",
296
297
  "evaluation-coverage",
297
- "observability"
298
+ "observability",
299
+ "metadata-quality"
298
300
  ])
299
301
  ).optional().describe('Compliance rule packs to evaluate during "agentspec audit". Each pack groups related rules. Omit to run all packs.'),
300
302
  suppressions: z.array(ComplianceSuppressionSchema).optional().describe("Rules to suppress in audit output. Each suppression requires a reason and optional expiry date. Over-suppression is itself flagged."),
@@ -502,7 +504,7 @@ function loadManifest(filePath, opts = {}) {
502
504
  }
503
505
  let parsed;
504
506
  try {
505
- parsed = yaml.load(raw);
507
+ parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
506
508
  } catch (err) {
507
509
  throw new Error(`Invalid YAML in ${absPath}
508
510
  ${String(err)}`);
@@ -1066,8 +1068,6 @@ async function checkAws() {
1066
1068
  clearTimeout(timer);
1067
1069
  }
1068
1070
  }
1069
-
1070
- // src/health/checks/service.check.ts
1071
1071
  var TIMEOUT_MS = 3e3;
1072
1072
  async function runServiceChecks(services) {
1073
1073
  return Promise.all(services.map((svc) => checkService(svc)));
@@ -1143,11 +1143,25 @@ function parseConnectionUrl(connection) {
1143
1143
  }
1144
1144
  function classifyHost(host) {
1145
1145
  const h = host.replace(/^\[(.+)\]$/, "$1").toLowerCase();
1146
- if (h === "0.0.0.0") return "unspecified address 0.0.0.0 is not a valid service host";
1147
- if (h === "::1" || h === "localhost") return "loopback address is not probed from service checks";
1148
- if (h.startsWith("127.")) return "IPv4 loopback (127.x.x.x) is not probed from service checks";
1149
- if (h.startsWith("169.254.")) return "link-local address (169.254.x.x) blocked to prevent instance-metadata SSRF";
1150
- if (h.startsWith("fe80:")) return "IPv6 link-local (fe80::/10) blocked to prevent SSRF";
1146
+ if (h === "localhost") return "loopback address is not probed from service checks";
1147
+ const ipVersion = isIP(h);
1148
+ if (ipVersion === 4) {
1149
+ if (h === "0.0.0.0") return "unspecified address 0.0.0.0 is not a valid service host";
1150
+ if (h.startsWith("127.")) return "IPv4 loopback (127.x.x.x) is not probed from service checks";
1151
+ if (h.startsWith("169.254.")) return "link-local address (169.254.x.x) blocked to prevent instance-metadata SSRF";
1152
+ if (h.startsWith("10.")) return "RFC 1918 private address (10.0.0.0/8) blocked to prevent internal SSRF";
1153
+ if (h.startsWith("192.168.")) return "RFC 1918 private address (192.168.0.0/16) blocked to prevent internal SSRF";
1154
+ if (h.startsWith("172.")) {
1155
+ const second = parseInt(h.split(".")[1] ?? "0", 10);
1156
+ if (second >= 16 && second <= 31) {
1157
+ return "RFC 1918 private address (172.16.0.0/12) blocked to prevent internal SSRF";
1158
+ }
1159
+ }
1160
+ }
1161
+ if (ipVersion === 6) {
1162
+ if (h === "::1") return "loopback address is not probed from service checks";
1163
+ if (h.startsWith("fe80:")) return "IPv6 link-local (fe80::/10) blocked to prevent SSRF";
1164
+ }
1151
1165
  return null;
1152
1166
  }
1153
1167
  function getDefaultPort(scheme) {
@@ -1942,6 +1956,49 @@ var observabilityRules = [
1942
1956
  }
1943
1957
  ];
1944
1958
 
1959
+ // src/audit/rules/metadata.rules.ts
1960
+ var metadataRules = [
1961
+ {
1962
+ id: "META-01",
1963
+ pack: "metadata-quality",
1964
+ title: "Agent description declared",
1965
+ description: "Agents should have a non-empty description for fleet discovery and documentation",
1966
+ severity: "low",
1967
+ evidenceLevel: "declarative",
1968
+ check(manifest) {
1969
+ const desc = manifest.metadata.description;
1970
+ const pass = typeof desc === "string" && desc.trim().length > 0;
1971
+ return {
1972
+ pass,
1973
+ message: pass ? void 0 : "No description declared in metadata. Agents without descriptions are hard to discover in a fleet.",
1974
+ path: "/metadata/description",
1975
+ recommendation: "Add a concise metadata.description explaining what the agent does",
1976
+ references: []
1977
+ };
1978
+ }
1979
+ },
1980
+ {
1981
+ id: "META-02",
1982
+ pack: "metadata-quality",
1983
+ title: "Model temperature is production-safe",
1984
+ description: "Temperature above 1.5 causes unpredictable outputs that are unsuitable for production",
1985
+ severity: "medium",
1986
+ evidenceLevel: "declarative",
1987
+ check(manifest) {
1988
+ const temperature = manifest.spec.model.parameters?.temperature;
1989
+ if (temperature === void 0) return { pass: true };
1990
+ const pass = temperature <= 1.5;
1991
+ return {
1992
+ pass,
1993
+ message: pass ? void 0 : `Model temperature is ${temperature} \u2014 values above 1.5 produce unreliable outputs in production.`,
1994
+ path: "/spec/model/parameters/temperature",
1995
+ recommendation: "Set spec.model.parameters.temperature to 1.0 or lower for production agents",
1996
+ references: []
1997
+ };
1998
+ }
1999
+ }
2000
+ ];
2001
+
1945
2002
  // src/audit/index.ts
1946
2003
  var SEVERITY_WEIGHTS = {
1947
2004
  critical: 4,
@@ -1955,7 +2012,8 @@ var ALL_RULES = [
1955
2012
  ...securityRules,
1956
2013
  ...memoryRules,
1957
2014
  ...evaluationRules,
1958
- ...observabilityRules
2015
+ ...observabilityRules,
2016
+ ...metadataRules
1959
2017
  ];
1960
2018
  var AUDIT_RULE_IDS = new Set(ALL_RULES.map((r) => r.id));
1961
2019
  function isProofRecord(r) {
@@ -2119,6 +2177,62 @@ function generateAdapter(manifest, framework, options) {
2119
2177
  return adapter.generate(manifest, options);
2120
2178
  }
2121
2179
 
2180
+ // src/agent/usage-ledger.ts
2181
+ function createEmptyEntry(modelId) {
2182
+ return { modelId, promptTokens: 0, completionTokens: 0, totalTokens: 0, callCount: 0 };
2183
+ }
2184
+ function buildSnapshot(counters, windowStart) {
2185
+ const models = [...counters.values()].map((e) => ({ ...e }));
2186
+ let totalTokens = 0;
2187
+ let totalCalls = 0;
2188
+ for (const m of models) {
2189
+ totalTokens += m.totalTokens;
2190
+ totalCalls += m.callCount;
2191
+ }
2192
+ return {
2193
+ windowStartedAt: windowStart.toISOString(),
2194
+ models,
2195
+ totalTokens,
2196
+ totalCalls
2197
+ };
2198
+ }
2199
+ var UsageLedger = class {
2200
+ counters = /* @__PURE__ */ new Map();
2201
+ windowStart = /* @__PURE__ */ new Date();
2202
+ /**
2203
+ * Record token usage for a single LLM call.
2204
+ * Call this once per LLM invocation with the model ID and token counts.
2205
+ */
2206
+ record(modelId, promptTokens, completionTokens) {
2207
+ const p = Math.max(0, promptTokens);
2208
+ const c = Math.max(0, completionTokens);
2209
+ let entry = this.counters.get(modelId);
2210
+ if (!entry) {
2211
+ entry = createEmptyEntry(modelId);
2212
+ this.counters.set(modelId, entry);
2213
+ }
2214
+ entry.promptTokens += p;
2215
+ entry.completionTokens += c;
2216
+ entry.totalTokens += p + c;
2217
+ entry.callCount += 1;
2218
+ }
2219
+ /**
2220
+ * Return a frozen snapshot of the current usage window.
2221
+ *
2222
+ * @param reset - When true (default), clears all counters and starts a new
2223
+ * window. Use reset=true in the heartbeat push so each window is shipped
2224
+ * exactly once. Use reset=false for inspection without draining.
2225
+ */
2226
+ snapshot(reset = true) {
2227
+ const snap = buildSnapshot(this.counters, this.windowStart);
2228
+ if (reset) {
2229
+ this.counters = /* @__PURE__ */ new Map();
2230
+ this.windowStart = /* @__PURE__ */ new Date();
2231
+ }
2232
+ return snap;
2233
+ }
2234
+ };
2235
+
2122
2236
  // src/agent/reporter.ts
2123
2237
  var AgentSpecReporter = class {
2124
2238
  constructor(manifest, opts = {}) {
@@ -2135,6 +2249,8 @@ var AgentSpecReporter = class {
2135
2249
  refreshing = false;
2136
2250
  stopped = false;
2137
2251
  registeredTools = /* @__PURE__ */ new Set();
2252
+ /** In-process token usage accumulator. */
2253
+ usage = new UsageLedger();
2138
2254
  /**
2139
2255
  * Register a tool handler by name.
2140
2256
  * Only registered tools report status: 'pass' in the live health check.
@@ -2224,12 +2340,13 @@ var AgentSpecReporter = class {
2224
2340
  try {
2225
2341
  const health = await this.getReport();
2226
2342
  const gap = runAudit(this.manifest);
2343
+ const usage = this.usage.snapshot(false);
2227
2344
  const trimmedChecks = [...health.checks];
2228
- let body = JSON.stringify({ health, gap });
2345
+ let body = JSON.stringify({ health, gap, usage });
2229
2346
  if (body.length > 65536) {
2230
2347
  while (trimmedChecks.length > 0) {
2231
2348
  trimmedChecks.pop();
2232
- body = JSON.stringify({ health: { ...health, checks: trimmedChecks }, gap });
2349
+ body = JSON.stringify({ health: { ...health, checks: trimmedChecks }, gap, usage });
2233
2350
  if (body.length <= 65536) break;
2234
2351
  }
2235
2352
  }
@@ -2248,7 +2365,9 @@ var AgentSpecReporter = class {
2248
2365
  opts.onError?.(new Error(sanitized));
2249
2366
  return;
2250
2367
  }
2251
- if (!res.ok) {
2368
+ if (res.ok) {
2369
+ this.usage.snapshot(true);
2370
+ } else {
2252
2371
  opts.onError?.(new Error(`Heartbeat failed: HTTP ${res.status}`));
2253
2372
  }
2254
2373
  } catch (err) {
@@ -2339,6 +2458,14 @@ function agentSpecFastifyPlugin(reporter) {
2339
2458
  reply.status(500).send({ error: String(err) });
2340
2459
  }
2341
2460
  });
2461
+ app.get("/agentspec/usage", async (_req, reply) => {
2462
+ try {
2463
+ const snapshot = reporter.usage.snapshot(false);
2464
+ reply.status(200).send(snapshot);
2465
+ } catch (err) {
2466
+ reply.status(500).send({ error: String(err) });
2467
+ }
2468
+ });
2342
2469
  };
2343
2470
  }
2344
2471
 
@@ -2347,27 +2474,45 @@ function agentSpecExpressRouter(reporter) {
2347
2474
  const handler = async (req, res, next) => {
2348
2475
  const method = req.method?.toUpperCase() ?? "GET";
2349
2476
  const path = req.path ?? req.url ?? "";
2350
- if (method !== "GET" || path !== "/health") {
2477
+ if (method !== "GET") {
2351
2478
  next();
2352
2479
  return;
2353
2480
  }
2354
- try {
2355
- const report = await reporter.getReport();
2356
- res.status(200).json(report);
2357
- } catch (err) {
2481
+ if (path === "/health") {
2358
2482
  try {
2359
- res.status(500).json({ error: String(err) });
2360
- } catch {
2361
- next(err);
2483
+ const report = await reporter.getReport();
2484
+ res.status(200).json(report);
2485
+ } catch (err) {
2486
+ try {
2487
+ res.status(500).json({ error: String(err) });
2488
+ } catch {
2489
+ next(err);
2490
+ }
2362
2491
  }
2492
+ return;
2493
+ }
2494
+ if (path === "/usage") {
2495
+ try {
2496
+ const snapshot = reporter.usage.snapshot(false);
2497
+ res.status(200).json(snapshot);
2498
+ } catch (err) {
2499
+ try {
2500
+ res.status(500).json({ error: String(err) });
2501
+ } catch {
2502
+ next(err);
2503
+ }
2504
+ }
2505
+ return;
2363
2506
  }
2507
+ next();
2364
2508
  };
2365
2509
  handler._routes = [
2366
- { path: "/health" }
2510
+ { path: "/health" },
2511
+ { path: "/usage" }
2367
2512
  ];
2368
2513
  return handler;
2369
2514
  }
2370
2515
 
2371
- export { AUDIT_RULE_IDS, AgentSpecReporter, LATEST_API_VERSION, ManifestSchema, agentSpecExpressRouter, agentSpecFastifyPlugin, collectEnvRefs, collectFileRefs, detectRefType, detectVersion, exportJsonSchema, generateAdapter, getAdapter, isLatestVersion, isProofRecord, listAdapters, loadManifest, migrateManifest, registerAdapter, resolveRef, resolveRefs, runAudit, runHealthCheck, runServiceChecks, scoreToGrade, tryLoadManifest };
2516
+ export { AUDIT_RULE_IDS, AgentSpecReporter, LATEST_API_VERSION, ManifestSchema, UsageLedger, agentSpecExpressRouter, agentSpecFastifyPlugin, collectEnvRefs, collectFileRefs, detectRefType, detectVersion, exportJsonSchema, generateAdapter, getAdapter, isLatestVersion, isProofRecord, listAdapters, loadManifest, migrateManifest, registerAdapter, resolveRef, resolveRefs, runAudit, runHealthCheck, runServiceChecks, scoreToGrade, tryLoadManifest };
2372
2517
  //# sourceMappingURL=index.js.map
2373
2518
  //# sourceMappingURL=index.js.map