@aumos/agent-gov 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,84 @@
+/**
+ * HTTP client for the agent-gov governance API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentGovClient } from "@aumos/agent-gov";
+ *
+ * const client = createAgentGovClient({ baseUrl: "http://localhost:8070" });
+ *
+ * const result = await client.checkCompliance({
+ *   agent_id: "my-agent",
+ *   policy_name: "default",
+ *   action: { type: "search", query: "user emails" },
+ * });
+ *
+ * if (result.ok && result.data.passed) {
+ *   console.log("Action approved by governance policy");
+ * }
+ * ```
+ */
+import type { ApiResult, AuditEntry, AuditLogQuery, CheckComplianceRequest, ComplianceCostReport, ComplianceReport, GenerateReportRequest, ValidatePolicyRequest, ValidatePolicyResponse } from "./types.js";
+/** Configuration options for the AgentGovClient. */
+export interface AgentGovClientConfig {
+    /** Base URL of the agent-gov server (e.g. "http://localhost:8070"). */
+    readonly baseUrl: string;
+    /** Optional request timeout in milliseconds (default: 30000). */
+    readonly timeoutMs?: number;
+    /** Optional extra HTTP headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Typed HTTP client for the agent-gov governance server. */
+export interface AgentGovClient {
+    /**
+     * Evaluate an agent action against a named policy.
+     *
+     * Sends the action payload to the governance engine and returns a full
+     * ComplianceReport with per-rule verdicts, pass/fail status, and severity.
+     *
+     * @param request - The agent ID, action payload, and target policy name.
+     * @returns A ComplianceReport with all rule verdicts and an overall verdict.
+     */
+    checkCompliance(request: CheckComplianceRequest): Promise<ApiResult<ComplianceReport>>;
+    /**
+     * Retrieve the audit log with optional filtering.
+     *
+     * Returns entries in reverse chronological order (most recent first).
+     *
+     * @param query - Optional filter parameters (agentId, policyName, verdict, limit).
+     * @returns Array of AuditEntry records matching the filter criteria.
+     */
+    getAuditLog(query?: AuditLogQuery): Promise<ApiResult<readonly AuditEntry[]>>;
+    /**
+     * Generate a cost-of-compliance report for a regulatory framework.
+     *
+     * Computes per-requirement cost estimates under the given automation
+     * scenario and returns aggregated totals with savings percentages.
+     *
+     * @param request - Framework name, automation coverage overrides, and hourly rate.
+     * @returns A ComplianceCostReport with full cost breakdown.
+     */
+    generateReport(request: GenerateReportRequest): Promise<ApiResult<ComplianceCostReport>>;
+    /**
+     * Validate a policy configuration without persisting it.
+     *
+     * Checks rule type references, parameter schemas, and structural
+     * correctness. Returns a list of validation errors when the policy
+     * is invalid.
+     *
+     * @param request - The full policy configuration to validate.
+     * @returns Validation result with error messages and enabled rule count.
+     */
+    validatePolicy(request: ValidatePolicyRequest): Promise<ApiResult<ValidatePolicyResponse>>;
+}
+/**
+ * Create a typed HTTP client for the agent-gov governance server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentGovClient instance.
+ */
+export declare function createAgentGovClient(config: AgentGovClientConfig): AgentGovClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAEV,SAAS,EACT,UAAU,EACV,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAMpB,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AA0DD,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,eAAe,CACb,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAExC;;;;;;;OAOG;IACH,WAAW,CACT,KAAK,CAAC,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC,CAAC;IAE7C;;;;;;;;OAQG;IACH,cAAc,CACZ,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAE5C;;;;;;;;;OASG;IACH,cAAc,CACZ,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC,CAAC;CAC/C;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAC3B,cAAc,CA4EhB"}

package/dist/client.js

@@ -0,0 +1,120 @@
+/**
+ * HTTP client for the agent-gov governance API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentGovClient } from "@aumos/agent-gov";
+ *
+ * const client = createAgentGovClient({ baseUrl: "http://localhost:8070" });
+ *
+ * const result = await client.checkCompliance({
+ *   agent_id: "my-agent",
+ *   policy_name: "default",
+ *   action: { type: "search", query: "user emails" },
+ * });
+ *
+ * if (result.ok && result.data.passed) {
+ *   console.log("Action approved by governance policy");
+ * }
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function fetchJson(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeoutId);
+        const body = await response.json();
+        if (!response.ok) {
+            const errorBody = body;
+            return {
+                ok: false,
+                error: {
+                    error: errorBody.error ?? "Unknown error",
+                    detail: errorBody.detail ?? "",
+                },
+                status: response.status,
+            };
+        }
+        return { ok: true, data: body };
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: { error: "Network error", detail: message },
+            status: 0,
+        };
+    }
+}
+function buildHeaders(extraHeaders) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...extraHeaders,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed HTTP client for the agent-gov governance server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentGovClient instance.
+ */
+export function createAgentGovClient(config) {
+    const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+    const baseHeaders = buildHeaders(extraHeaders);
+    return {
+        async checkCompliance(request) {
+            return fetchJson(`${baseUrl}/compliance/check`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async getAuditLog(query = {}) {
+            const params = new URLSearchParams();
+            if (query.agentId !== undefined) {
+                params.set("agent_id", query.agentId);
+            }
+            if (query.policyName !== undefined) {
+                params.set("policy_name", query.policyName);
+            }
+            if (query.verdict !== undefined) {
+                params.set("verdict", query.verdict);
+            }
+            if (query.limit !== undefined) {
+                params.set("limit", String(query.limit));
+            }
+            const queryString = params.toString();
+            const url = queryString
+                ? `${baseUrl}/audit/log?${queryString}`
+                : `${baseUrl}/audit/log`;
+            return fetchJson(url, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async generateReport(request) {
+            return fetchJson(`${baseUrl}/compliance/report`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async validatePolicy(request) {
+            return fetchJson(`${baseUrl}/policies/validate`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @aumos/agent-gov
+ *
+ * TypeScript client for the AumOS agent-gov governance framework.
+ * Provides policy evaluation, compliance checking, audit logging,
+ * and cost-of-compliance reporting.
+ */
+export type { AgentGovClient, AgentGovClientConfig } from "./client.js";
+export { createAgentGovClient } from "./client.js";
+export type { Severity, ComplianceFramework, AutomationLevel, AuditVerdict, PolicyRule, GovernanceConfig, RuleVerdict, ComplianceReport, AuditEntry, RequirementCostDetail, ComplianceCostReport, CheckComplianceRequest, ValidatePolicyRequest, ValidatePolicyResponse, GenerateReportRequest, AuditLogQuery, ApiError, ApiResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,YAAY,EACV,QAAQ,EACR,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,QAAQ,EACR,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aumos/agent-gov
+ *
+ * TypeScript client for the AumOS agent-gov governance framework.
+ * Provides policy evaluation, compliance checking, audit logging,
+ * and cost-of-compliance reporting.
+ */
+export { createAgentGovClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,240 @@
+/**
+ * TypeScript interfaces for the agent-gov governance framework.
+ *
+ * Mirrors the Pydantic/dataclass models defined in:
+ *   agent_gov.policy.schema     — PolicyRule, PolicyConfig, RuleConfig
+ *   agent_gov.policy.rule       — RuleVerdict
+ *   agent_gov.policy.result     — EvaluationReport
+ *   agent_gov.audit.entry       — AuditEntry
+ *   agent_gov.compliance_cost.calculator — CostReport
+ *
+ * All interfaces use readonly fields to match Python frozen models.
+ */
+/**
+ * Severity levels for policy rule violations.
+ * Maps to the Python Severity enum in agent_gov.policy.schema.
+ */
+export type Severity = "low" | "medium" | "high" | "critical";
+/**
+ * Compliance frameworks supported by the governance engine.
+ * Each identifier maps to a built-in requirement catalogue.
+ */
+export type ComplianceFramework = "eu_ai_act" | "gdpr" | "hipaa" | "soc2";
+/**
+ * Automation level for a compliance requirement.
+ * Controls how labour hours are estimated in cost calculations.
+ */
+export type AutomationLevel = "fully_automated" | "semi_automated" | "manual";
+/**
+ * Audit verdict — the outcome of a policy evaluation.
+ */
+export type AuditVerdict = "pass" | "fail";
+/**
+ * Configuration for a single rule within a policy.
+ * Maps to RuleConfig in agent_gov.policy.schema.
+ */
+export interface PolicyRule {
+    /** Human-readable label for this rule within the policy. */
+    readonly name: string;
+    /**
+     * Rule type identifier — matches the rule class `name` attribute used
+     * for rule registry lookup.
+     */
+    readonly type: string;
+    /** When false the rule is skipped during evaluation. Default true. */
+    readonly enabled: boolean;
+    /** Default severity applied to verdicts produced by this rule. */
+    readonly severity: Severity;
+    /** Arbitrary key/value parameters forwarded to the rule evaluate call. */
+    readonly params: Readonly<Record<string, unknown>>;
+}
+/**
+ * Top-level policy configuration.
+ * Maps to PolicyConfig in agent_gov.policy.schema.
+ */
+export interface GovernanceConfig {
+    /** Unique identifier for this policy. */
+    readonly name: string;
+    /** Semantic version string for tracking policy changes. */
+    readonly version: string;
+    /** Free-text description of what this policy governs. */
+    readonly description: string;
+    /** Ordered list of rule configurations to evaluate. */
+    readonly rules: readonly PolicyRule[];
+    /** Arbitrary string key/value metadata (author, team, ticket, etc.). */
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * Result produced by a single rule evaluation.
+ * Maps to RuleVerdict in agent_gov.policy.rule.
+ */
+export interface RuleVerdict {
+    /** The name of the rule that produced this verdict. */
+    readonly rule_name: string;
+    /** True when the action satisfies the rule; false when it violates it. */
+    readonly passed: boolean;
+    /** Severity level of this verdict. */
+    readonly severity: Severity;
+    /** Human-readable explanation, typically set when passed is false. */
+    readonly message: string;
+    /** Arbitrary structured data providing additional context. */
+    readonly details: Readonly<Record<string, unknown>>;
+}
+/**
+ * Complete result of evaluating one action against a policy.
+ * Maps to EvaluationReport in agent_gov.policy.result.
+ */
+export interface ComplianceReport {
+    /** Name of the policy that generated this report. */
+    readonly policy_name: string;
+    /** The original action dictionary that was evaluated. */
+    readonly action: Readonly<Record<string, unknown>>;
+    /** One RuleVerdict per enabled rule that was evaluated. */
+    readonly verdicts: readonly RuleVerdict[];
+    /** True only when all verdicts report passed=true. */
+    readonly passed: boolean;
+    /** ISO-8601 UTC timestamp at which the evaluation completed. */
+    readonly timestamp: string;
+    /** Number of rules that flagged a violation. */
+    readonly violation_count: number;
+    /** Highest severity among all failed verdicts; "none" when no failures. */
+    readonly highest_severity: Severity | "none";
+}
+/**
+ * A single immutable audit log record.
+ * Maps to AuditEntry in agent_gov.audit.entry.
+ */
+export interface AuditEntry {
+    /** Unique identifier for the agent that performed the action. */
+    readonly agent_id: string;
+    /** Short category/type string for the action (e.g. "search", "write"). */
+    readonly action_type: string;
+    /** Full action payload as passed to the policy evaluator. */
+    readonly action_data: Readonly<Record<string, unknown>>;
+    /** Overall verdict: "pass" or "fail". */
+    readonly verdict: AuditVerdict;
+    /** Name of the policy that produced the verdict. */
+    readonly policy_name: string;
+    /** ISO-8601 UTC timestamp of the evaluation. */
+    readonly timestamp: string;
+    /** Arbitrary additional context (run ID, environment, etc.). */
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * Per-requirement cost detail line within a CostReport.
+ */
+export interface RequirementCostDetail {
+    /** Short unique identifier within the framework. */
+    readonly requirement_id: string;
+    /** Plain-language description of the requirement. */
+    readonly description: string;
+    /** Current automation level for this requirement. */
+    readonly automation_level: AutomationLevel;
+    /** Hours estimate when handled manually. */
+    readonly hours_manual: number;
+    /** Hours estimate under the current automation scenario. */
+    readonly hours_automated: number;
+    /** Cost in currency units under full manual mode. */
+    readonly cost_manual: number;
+    /** Cost in currency units under the current automation scenario. */
+    readonly cost_automated: number;
+    /** Cost saving from automation (cost_manual - cost_automated). */
+    readonly savings: number;
+}
+/**
+ * Cost-of-compliance report for a single framework and automation scenario.
+ * Maps to CostReport in agent_gov.compliance_cost.calculator.
+ */
+export interface ComplianceCostReport {
+    /** The regulatory framework being reported on. */
+    readonly framework: ComplianceFramework | string;
+    /** Total number of requirements in the framework. */
+    readonly total_requirements: number;
+    /** Count of requirements classified as fully_automated. */
+    readonly automated_count: number;
+    /** Count of semi_automated requirements. */
+    readonly semi_automated_count: number;
+    /** Count of manual requirements. */
+    readonly manual_count: number;
+    /** Sum of manual-mode hours across all requirements. */
+    readonly total_hours_manual: number;
+    /** Sum of automated-mode hours across all requirements. */
+    readonly total_hours_automated: number;
+    /** Total cost in currency units under fully manual mode. */
+    readonly total_cost_manual: number;
+    /** Total cost in currency units under the current automation scenario. */
+    readonly total_cost_with_automation: number;
+    /** Percentage cost reduction from automation. */
+    readonly savings_percentage: number;
+    /** Hourly rate used in the calculation. */
+    readonly hourly_rate: number;
+    /** Per-requirement cost detail lines. */
+    readonly requirement_details: readonly RequirementCostDetail[];
+}
+/**
+ * Request body for the checkCompliance endpoint.
+ */
+export interface CheckComplianceRequest {
+    /** Identifier of the agent performing the action. */
+    readonly agent_id: string;
+    /** The action payload to evaluate. */
+    readonly action: Readonly<Record<string, unknown>>;
+    /** Name of the policy to evaluate against. */
+    readonly policy_name: string;
+}
+/**
+ * Request body for the validatePolicy endpoint.
+ */
+export interface ValidatePolicyRequest {
+    /** The full policy configuration to validate. */
+    readonly policy: GovernanceConfig;
+}
+/**
+ * Response from the validatePolicy endpoint. */
+export interface ValidatePolicyResponse {
+    /** Whether the policy configuration is valid. */
+    readonly valid: boolean;
+    /** Validation error messages; empty when valid. */
+    readonly errors: readonly string[];
+    /** Number of enabled rules in the policy. */
+    readonly enabled_rule_count: number;
+}
+/**
+ * Request body for the generateReport endpoint.
+ */
+export interface GenerateReportRequest {
+    /** The regulatory framework to generate a cost report for. */
+    readonly framework: ComplianceFramework | string;
+    /** Automation level overrides per requirement_id. */
+    readonly automation_coverage?: Readonly<Record<string, AutomationLevel>>;
+    /** Hourly labour rate in currency units (default 150.0). */
+    readonly hourly_rate?: number;
+}
+/**
+ * Query parameters for the getAuditLog endpoint.
+ */
+export interface AuditLogQuery {
+    /** Filter by agent ID. */
+    readonly agentId?: string;
+    /** Filter by policy name. */
+    readonly policyName?: string;
+    /** Filter by verdict. */
+    readonly verdict?: AuditVerdict;
+    /** Maximum number of entries to return (default 100). */
+    readonly limit?: number;
+}
+/** Standard error payload returned by the agent-gov API. */
+export interface ApiError {
+    readonly error: string;
+    readonly detail: string;
+}
+/** Result type for all client operations. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: ApiError;
+    readonly status: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1E;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,QAAQ,CAAC;AAE9E;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAM3C;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAMD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC9C;AAMD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAMD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,gBAAgB,EAAE,eAAe,CAAC;IAC3C,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACjD,qDAAqD;IACrD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,4CAA4C;IAC5C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,oCAAoC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;IAC5C,iDAAiD;IACjD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAChE;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED;gDACgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACjD,qDAAqD;IACrD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IACzE,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD,4DAA4D;AAC5D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,MAAM,SAAS,CAAC,CAAC,IACnB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACvC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * TypeScript interfaces for the agent-gov governance framework.
+ *
+ * Mirrors the Pydantic/dataclass models defined in:
+ *   agent_gov.policy.schema     — PolicyRule, PolicyConfig, RuleConfig
+ *   agent_gov.policy.rule       — RuleVerdict
+ *   agent_gov.policy.result     — EvaluationReport
+ *   agent_gov.audit.entry       — AuditEntry
+ *   agent_gov.compliance_cost.calculator — CostReport
+ *
+ * All interfaces use readonly fields to match Python frozen models.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@aumos/agent-gov",
+  "version": "0.1.0",
+  "description": "TypeScript client for the AumOS agent-gov governance framework — policy evaluation, compliance checking, and audit logging",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "aumos",
+    "agent-gov",
+    "governance",
+    "compliance",
+    "policy",
+    "audit",
+    "eu-ai-act",
+    "gdpr",
+    "hipaa",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aumos-ai/agent-gov"
+  }
+}

package/src/client.ts

@@ -0,0 +1,252 @@
+/**
+ * HTTP client for the agent-gov governance API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentGovClient } from "@aumos/agent-gov";
+ *
+ * const client = createAgentGovClient({ baseUrl: "http://localhost:8070" });
+ *
+ * const result = await client.checkCompliance({
+ *   agent_id: "my-agent",
+ *   policy_name: "default",
+ *   action: { type: "search", query: "user emails" },
+ * });
+ *
+ * if (result.ok && result.data.passed) {
+ *   console.log("Action approved by governance policy");
+ * }
+ * ```
+ */
+
+import type {
+  ApiError,
+  ApiResult,
+  AuditEntry,
+  AuditLogQuery,
+  CheckComplianceRequest,
+  ComplianceCostReport,
+  ComplianceReport,
+  GenerateReportRequest,
+  ValidatePolicyRequest,
+  ValidatePolicyResponse,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration options for the AgentGovClient. */
+export interface AgentGovClientConfig {
+  /** Base URL of the agent-gov server (e.g. "http://localhost:8070"). */
+  readonly baseUrl: string;
+  /** Optional request timeout in milliseconds (default: 30000). */
+  readonly timeoutMs?: number;
+  /** Optional extra HTTP headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<ApiResult<T>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    const body = await response.json() as unknown;
+
+    if (!response.ok) {
+      const errorBody = body as Partial<ApiError>;
+      return {
+        ok: false,
+        error: {
+          error: errorBody.error ?? "Unknown error",
+          detail: errorBody.detail ?? "",
+        },
+        status: response.status,
+      };
+    }
+
+    return { ok: true, data: body as T };
+  } catch (err: unknown) {
+    clearTimeout(timeoutId);
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: { error: "Network error", detail: message },
+      status: 0,
+    };
+  }
+}
+
+function buildHeaders(
+  extraHeaders: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+/** Typed HTTP client for the agent-gov governance server. */
+export interface AgentGovClient {
+  /**
+   * Evaluate an agent action against a named policy.
+   *
+   * Sends the action payload to the governance engine and returns a full
+   * ComplianceReport with per-rule verdicts, pass/fail status, and severity.
+   *
+   * @param request - The agent ID, action payload, and target policy name.
+   * @returns A ComplianceReport with all rule verdicts and an overall verdict.
+   */
+  checkCompliance(
+    request: CheckComplianceRequest,
+  ): Promise<ApiResult<ComplianceReport>>;
+
+  /**
+   * Retrieve the audit log with optional filtering.
+   *
+   * Returns entries in reverse chronological order (most recent first).
+   *
+   * @param query - Optional filter parameters (agentId, policyName, verdict, limit).
+   * @returns Array of AuditEntry records matching the filter criteria.
+   */
+  getAuditLog(
+    query?: AuditLogQuery,
+  ): Promise<ApiResult<readonly AuditEntry[]>>;
+
+  /**
+   * Generate a cost-of-compliance report for a regulatory framework.
+   *
+   * Computes per-requirement cost estimates under the given automation
+   * scenario and returns aggregated totals with savings percentages.
+   *
+   * @param request - Framework name, automation coverage overrides, and hourly rate.
+   * @returns A ComplianceCostReport with full cost breakdown.
+   */
+  generateReport(
+    request: GenerateReportRequest,
+  ): Promise<ApiResult<ComplianceCostReport>>;
+
+  /**
+   * Validate a policy configuration without persisting it.
+   *
+   * Checks rule type references, parameter schemas, and structural
+   * correctness. Returns a list of validation errors when the policy
+   * is invalid.
+   *
+   * @param request - The full policy configuration to validate.
+   * @returns Validation result with error messages and enabled rule count.
+   */
+  validatePolicy(
+    request: ValidatePolicyRequest,
+  ): Promise<ApiResult<ValidatePolicyResponse>>;
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed HTTP client for the agent-gov governance server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentGovClient instance.
+ */
+export function createAgentGovClient(
+  config: AgentGovClientConfig,
+): AgentGovClient {
+  const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+  const baseHeaders = buildHeaders(extraHeaders);
+
+  return {
+    async checkCompliance(
+      request: CheckComplianceRequest,
+    ): Promise<ApiResult<ComplianceReport>> {
+      return fetchJson<ComplianceReport>(
+        `${baseUrl}/compliance/check`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async getAuditLog(
+      query: AuditLogQuery = {},
+    ): Promise<ApiResult<readonly AuditEntry[]>> {
+      const params = new URLSearchParams();
+      if (query.agentId !== undefined) {
+        params.set("agent_id", query.agentId);
+      }
+      if (query.policyName !== undefined) {
+        params.set("policy_name", query.policyName);
+      }
+      if (query.verdict !== undefined) {
+        params.set("verdict", query.verdict);
+      }
+      if (query.limit !== undefined) {
+        params.set("limit", String(query.limit));
+      }
+
+      const queryString = params.toString();
+      const url = queryString
+        ? `${baseUrl}/audit/log?${queryString}`
+        : `${baseUrl}/audit/log`;
+
+      return fetchJson<readonly AuditEntry[]>(
+        url,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async generateReport(
+      request: GenerateReportRequest,
+    ): Promise<ApiResult<ComplianceCostReport>> {
+      return fetchJson<ComplianceCostReport>(
+        `${baseUrl}/compliance/report`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async validatePolicy(
+      request: ValidatePolicyRequest,
+    ): Promise<ApiResult<ValidatePolicyResponse>> {
+      return fetchJson<ValidatePolicyResponse>(
+        `${baseUrl}/policies/validate`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @aumos/agent-gov
+ *
+ * TypeScript client for the AumOS agent-gov governance framework.
+ * Provides policy evaluation, compliance checking, audit logging,
+ * and cost-of-compliance reporting.
+ */
+
+// Client and configuration
+export type { AgentGovClient, AgentGovClientConfig } from "./client.js";
+export { createAgentGovClient } from "./client.js";
+
+// Core governance types
+export type {
+  Severity,
+  ComplianceFramework,
+  AutomationLevel,
+  AuditVerdict,
+  PolicyRule,
+  GovernanceConfig,
+  RuleVerdict,
+  ComplianceReport,
+  AuditEntry,
+  RequirementCostDetail,
+  ComplianceCostReport,
+  CheckComplianceRequest,
+  ValidatePolicyRequest,
+  ValidatePolicyResponse,
+  GenerateReportRequest,
+  AuditLogQuery,
+  ApiError,
+  ApiResult,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,280 @@
+/**
+ * TypeScript interfaces for the agent-gov governance framework.
+ *
+ * Mirrors the Pydantic/dataclass models defined in:
+ *   agent_gov.policy.schema     — PolicyRule, PolicyConfig, RuleConfig
+ *   agent_gov.policy.rule       — RuleVerdict
+ *   agent_gov.policy.result     — EvaluationReport
+ *   agent_gov.audit.entry       — AuditEntry
+ *   agent_gov.compliance_cost.calculator — CostReport
+ *
+ * All interfaces use readonly fields to match Python frozen models.
+ */
+
+// ---------------------------------------------------------------------------
+// Enumerations
+// ---------------------------------------------------------------------------
+
+/**
+ * Severity levels for policy rule violations.
+ * Maps to the Python Severity enum in agent_gov.policy.schema.
+ */
+export type Severity = "low" | "medium" | "high" | "critical";
+
+/**
+ * Compliance frameworks supported by the governance engine.
+ * Each identifier maps to a built-in requirement catalogue.
+ */
+export type ComplianceFramework = "eu_ai_act" | "gdpr" | "hipaa" | "soc2";
+
+/**
+ * Automation level for a compliance requirement.
+ * Controls how labour hours are estimated in cost calculations.
+ */
+export type AutomationLevel = "fully_automated" | "semi_automated" | "manual";
+
+/**
+ * Audit verdict — the outcome of a policy evaluation.
+ */
+export type AuditVerdict = "pass" | "fail";
+
+// ---------------------------------------------------------------------------
+// Policy rule types
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for a single rule within a policy.
+ * Maps to RuleConfig in agent_gov.policy.schema.
+ */
+export interface PolicyRule {
+  /** Human-readable label for this rule within the policy. */
+  readonly name: string;
+  /**
+   * Rule type identifier — matches the rule class `name` attribute used
+   * for rule registry lookup.
+   */
+  readonly type: string;
+  /** When false the rule is skipped during evaluation. Default true. */
+  readonly enabled: boolean;
+  /** Default severity applied to verdicts produced by this rule. */
+  readonly severity: Severity;
+  /** Arbitrary key/value parameters forwarded to the rule evaluate call. */
+  readonly params: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Top-level policy configuration.
+ * Maps to PolicyConfig in agent_gov.policy.schema.
+ */
+export interface GovernanceConfig {
+  /** Unique identifier for this policy. */
+  readonly name: string;
+  /** Semantic version string for tracking policy changes. */
+  readonly version: string;
+  /** Free-text description of what this policy governs. */
+  readonly description: string;
+  /** Ordered list of rule configurations to evaluate. */
+  readonly rules: readonly PolicyRule[];
+  /** Arbitrary string key/value metadata (author, team, ticket, etc.). */
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Rule verdict and evaluation report
+// ---------------------------------------------------------------------------
+
+/**
+ * Result produced by a single rule evaluation.
+ * Maps to RuleVerdict in agent_gov.policy.rule.
+ */
+export interface RuleVerdict {
+  /** The name of the rule that produced this verdict. */
+  readonly rule_name: string;
+  /** True when the action satisfies the rule; false when it violates it. */
+  readonly passed: boolean;
+  /** Severity level of this verdict. */
+  readonly severity: Severity;
+  /** Human-readable explanation, typically set when passed is false. */
+  readonly message: string;
+  /** Arbitrary structured data providing additional context. */
+  readonly details: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Complete result of evaluating one action against a policy.
+ * Maps to EvaluationReport in agent_gov.policy.result.
+ */
+export interface ComplianceReport {
+  /** Name of the policy that generated this report. */
+  readonly policy_name: string;
+  /** The original action dictionary that was evaluated. */
+  readonly action: Readonly<Record<string, unknown>>;
+  /** One RuleVerdict per enabled rule that was evaluated. */
+  readonly verdicts: readonly RuleVerdict[];
+  /** True only when all verdicts report passed=true. */
+  readonly passed: boolean;
+  /** ISO-8601 UTC timestamp at which the evaluation completed. */
+  readonly timestamp: string;
+  /** Number of rules that flagged a violation. */
+  readonly violation_count: number;
+  /** Highest severity among all failed verdicts; "none" when no failures. */
+  readonly highest_severity: Severity | "none";
+}
+
+// ---------------------------------------------------------------------------
+// Audit log
+// ---------------------------------------------------------------------------
+
+/**
+ * A single immutable audit log record.
+ * Maps to AuditEntry in agent_gov.audit.entry.
+ */
+export interface AuditEntry {
+  /** Unique identifier for the agent that performed the action. */
+  readonly agent_id: string;
+  /** Short category/type string for the action (e.g. "search", "write"). */
+  readonly action_type: string;
+  /** Full action payload as passed to the policy evaluator. */
+  readonly action_data: Readonly<Record<string, unknown>>;
+  /** Overall verdict: "pass" or "fail". */
+  readonly verdict: AuditVerdict;
+  /** Name of the policy that produced the verdict. */
+  readonly policy_name: string;
+  /** ISO-8601 UTC timestamp of the evaluation. */
+  readonly timestamp: string;
+  /** Arbitrary additional context (run ID, environment, etc.). */
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Compliance cost types
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-requirement cost detail line within a CostReport.
+ */
+export interface RequirementCostDetail {
+  /** Short unique identifier within the framework. */
+  readonly requirement_id: string;
+  /** Plain-language description of the requirement. */
+  readonly description: string;
+  /** Current automation level for this requirement. */
+  readonly automation_level: AutomationLevel;
+  /** Hours estimate when handled manually. */
+  readonly hours_manual: number;
+  /** Hours estimate under the current automation scenario. */
+  readonly hours_automated: number;
+  /** Cost in currency units under full manual mode. */
+  readonly cost_manual: number;
+  /** Cost in currency units under the current automation scenario. */
+  readonly cost_automated: number;
+  /** Cost saving from automation (cost_manual - cost_automated). */
+  readonly savings: number;
+}
+
+/**
+ * Cost-of-compliance report for a single framework and automation scenario.
+ * Maps to CostReport in agent_gov.compliance_cost.calculator.
+ */
+export interface ComplianceCostReport {
+  /** The regulatory framework being reported on. */
+  readonly framework: ComplianceFramework | string;
+  /** Total number of requirements in the framework. */
+  readonly total_requirements: number;
+  /** Count of requirements classified as fully_automated. */
+  readonly automated_count: number;
+  /** Count of semi_automated requirements. */
+  readonly semi_automated_count: number;
+  /** Count of manual requirements. */
+  readonly manual_count: number;
+  /** Sum of manual-mode hours across all requirements. */
+  readonly total_hours_manual: number;
+  /** Sum of automated-mode hours across all requirements. */
+  readonly total_hours_automated: number;
+  /** Total cost in currency units under fully manual mode. */
+  readonly total_cost_manual: number;
+  /** Total cost in currency units under the current automation scenario. */
+  readonly total_cost_with_automation: number;
+  /** Percentage cost reduction from automation. */
+  readonly savings_percentage: number;
+  /** Hourly rate used in the calculation. */
+  readonly hourly_rate: number;
+  /** Per-requirement cost detail lines. */
+  readonly requirement_details: readonly RequirementCostDetail[];
+}
+
+// ---------------------------------------------------------------------------
+// Request payload types
+// ---------------------------------------------------------------------------
+
+/**
+ * Request body for the checkCompliance endpoint.
+ */
+export interface CheckComplianceRequest {
+  /** Identifier of the agent performing the action. */
+  readonly agent_id: string;
+  /** The action payload to evaluate. */
+  readonly action: Readonly<Record<string, unknown>>;
+  /** Name of the policy to evaluate against. */
+  readonly policy_name: string;
+}
+
+/**
+ * Request body for the validatePolicy endpoint.
+ */
+export interface ValidatePolicyRequest {
+  /** The full policy configuration to validate. */
+  readonly policy: GovernanceConfig;
+}
+
+/**
+ * Response from the validatePolicy endpoint. */
+export interface ValidatePolicyResponse {
+  /** Whether the policy configuration is valid. */
+  readonly valid: boolean;
+  /** Validation error messages; empty when valid. */
+  readonly errors: readonly string[];
+  /** Number of enabled rules in the policy. */
+  readonly enabled_rule_count: number;
+}
+
+/**
+ * Request body for the generateReport endpoint.
+ */
+export interface GenerateReportRequest {
+  /** The regulatory framework to generate a cost report for. */
+  readonly framework: ComplianceFramework | string;
+  /** Automation level overrides per requirement_id. */
+  readonly automation_coverage?: Readonly<Record<string, AutomationLevel>>;
+  /** Hourly labour rate in currency units (default 150.0). */
+  readonly hourly_rate?: number;
+}
+
+/**
+ * Query parameters for the getAuditLog endpoint.
+ */
+export interface AuditLogQuery {
+  /** Filter by agent ID. */
+  readonly agentId?: string;
+  /** Filter by policy name. */
+  readonly policyName?: string;
+  /** Filter by verdict. */
+  readonly verdict?: AuditVerdict;
+  /** Maximum number of entries to return (default 100). */
+  readonly limit?: number;
+}
+
+// ---------------------------------------------------------------------------
+// API result wrapper (shared pattern)
+// ---------------------------------------------------------------------------
+
+/** Standard error payload returned by the agent-gov API. */
+export interface ApiError {
+  readonly error: string;
+  readonly detail: string;
+}
+
+/** Result type for all client operations. */
+export type ApiResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ApiError; readonly status: number };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}