@agentproto/governance-engine 0.1.0

package/dist/tools/index.d.ts

@@ -0,0 +1,169 @@
+import * as _agentproto_tool from '@agentproto/tool';
+import { G as GovernanceConfig } from '../workspace-config-vgR1Ieoo.js';
+
+/**
+ * AIP-14 contract for signing an artifact.
+ *
+ * `governanceConfig` is read from the per-call `context` (validated by
+ * `contextSchema`) — a single tool instance serves multiple workspaces /
+ * tenants without re-instantiation. Hosts that wire the tool through a
+ * Mastra adapter use `resolveContext` to project per-request guildId →
+ * config.
+ *
+ * Input fields use AIP-27 `Ref` compact strings — `artifact: "local:..."`,
+ * `signer: "operator:..."`. The body lives on the AIP-30 PROVIDER
+ * (`@agentproto/governance-engine/provider`); this file carries only
+ * the abstract contract per AIP-14.
+ */
+declare const signArtifactTool: _agentproto_tool.ToolHandle<{
+    artifact: string;
+    signer: string;
+    signerKind: "external" | "operator" | "user" | "counterparty" | "agent";
+    method: "typed_name" | "agent_confirm" | "click_through" | "esign_external";
+    evidence: unknown;
+    signerEmail?: string | undefined;
+    expectedDocumentHash?: string | undefined;
+    idempotencyKey?: string | undefined;
+}, {
+    signaturePath: string;
+    auditLogPath: string;
+    auditLineIndex: number;
+    documentHash: string;
+}, {
+    governanceConfig: GovernanceConfig;
+}>;
+
+/**
+ * AIP-14 contract for appending an event to the workspace audit log.
+ *
+ * Reads `governanceConfig` from the per-call context (validated by
+ * `contextSchema`). Body lives on the AIP-30 PROVIDER
+ * (`@agentproto/governance-engine/provider`).
+ */
+declare const recordAuditEventTool: _agentproto_tool.ToolHandle<{
+    actorKind: "operator" | "user" | "counterparty" | "agent" | "system";
+    actor: string | null;
+    entityType: string;
+    entity: string;
+    action: string;
+    scopeDir?: string | undefined;
+    payload?: Record<string, unknown> | undefined;
+    requestId?: string | undefined;
+    traceId?: string | undefined;
+    idempotencyKey?: string | undefined;
+}, {
+    logPath: string;
+    lineIndex: number;
+    anchored: boolean;
+    signature: string;
+}, {
+    governanceConfig: GovernanceConfig;
+}>;
+
+/**
+ * AIP-14 contract for registering pending signatures on an artifact.
+ *
+ * Reads `governanceConfig` from per-call context. Body lives on the
+ * AIP-30 PROVIDER (`@agentproto/governance-engine/provider`).
+ */
+declare const requestSignaturesTool: _agentproto_tool.ToolHandle<{
+    artifact: string;
+    requiredSignatures: {
+        signer: string;
+        method?: "typed_name" | "agent_confirm" | "click_through" | "esign_external" | undefined;
+        weight?: number | undefined;
+        deadline?: string | undefined;
+    }[];
+}, {
+    added: number;
+}, {
+    governanceConfig: GovernanceConfig;
+}>;
+
+/**
+ * AIP-14 contract for the read-only query of pending signatures.
+ *
+ * Reads `governanceConfig` from per-call context. Body lives on the
+ * AIP-30 PROVIDER (`@agentproto/governance-engine/provider`).
+ */
+declare const listPendingSignaturesTool: _agentproto_tool.ToolHandle<{
+    signer: string;
+}, {
+    pending: {
+        artifactPath: string;
+        requestedAt: string;
+        deadline?: string | undefined;
+        method?: string | undefined;
+        weight?: number | undefined;
+    }[];
+}, {
+    governanceConfig: GovernanceConfig;
+}>;
+
+declare const governanceTools: {
+    readonly signArtifact: _agentproto_tool.ToolHandle<{
+        artifact: string;
+        signer: string;
+        signerKind: "external" | "operator" | "user" | "counterparty" | "agent";
+        method: "typed_name" | "agent_confirm" | "click_through" | "esign_external";
+        evidence: unknown;
+        signerEmail?: string | undefined;
+        expectedDocumentHash?: string | undefined;
+        idempotencyKey?: string | undefined;
+    }, {
+        signaturePath: string;
+        auditLogPath: string;
+        auditLineIndex: number;
+        documentHash: string;
+    }, {
+        governanceConfig: GovernanceConfig;
+    }>;
+    readonly recordAuditEvent: _agentproto_tool.ToolHandle<{
+        actorKind: "operator" | "user" | "counterparty" | "agent" | "system";
+        actor: string | null;
+        entityType: string;
+        entity: string;
+        action: string;
+        scopeDir?: string | undefined;
+        payload?: Record<string, unknown> | undefined;
+        requestId?: string | undefined;
+        traceId?: string | undefined;
+        idempotencyKey?: string | undefined;
+    }, {
+        logPath: string;
+        lineIndex: number;
+        anchored: boolean;
+        signature: string;
+    }, {
+        governanceConfig: GovernanceConfig;
+    }>;
+    readonly requestSignatures: _agentproto_tool.ToolHandle<{
+        artifact: string;
+        requiredSignatures: {
+            signer: string;
+            method?: "typed_name" | "agent_confirm" | "click_through" | "esign_external" | undefined;
+            weight?: number | undefined;
+            deadline?: string | undefined;
+        }[];
+    }, {
+        added: number;
+    }, {
+        governanceConfig: GovernanceConfig;
+    }>;
+    readonly listPendingSignatures: _agentproto_tool.ToolHandle<{
+        signer: string;
+    }, {
+        pending: {
+            artifactPath: string;
+            requestedAt: string;
+            deadline?: string | undefined;
+            method?: string | undefined;
+            weight?: number | undefined;
+        }[];
+    }, {
+        governanceConfig: GovernanceConfig;
+    }>;
+};
+type GovernanceToolBundle = typeof governanceTools;
+
+export { type GovernanceToolBundle, governanceTools, listPendingSignaturesTool, recordAuditEventTool, requestSignaturesTool, signArtifactTool };

package/dist/tools/index.mjs

@@ -0,0 +1,22 @@
+import { listPendingSignaturesTool, requestSignaturesTool, recordAuditEventTool, signArtifactTool } from '../chunk-NXMY54BX.mjs';
+export { listPendingSignaturesTool, recordAuditEventTool, requestSignaturesTool, signArtifactTool } from '../chunk-NXMY54BX.mjs';
+import '../chunk-M7I5HTGN.mjs';
+
+/**
+ * @agentproto/governance-engine v0.1.0-alpha
+ * Reference engine for agentgovernance/v1 — audit chain + sign artifact +
+ * pending-signatures index, all routed through IGovernanceFilesystem so the
+ * same code runs against Node fs, Supabase Storage, S3, or in-memory.
+ */
+
+// src/tools/index.ts
+var governanceTools = {
+  signArtifact: signArtifactTool,
+  recordAuditEvent: recordAuditEventTool,
+  requestSignatures: requestSignaturesTool,
+  listPendingSignatures: listPendingSignaturesTool
+};
+
+export { governanceTools };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/tools/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AA0BO,IAAM,eAAA,GAAkB;AAAA,EAC7B,YAAA,EAAc,gBAAA;AAAA,EACd,gBAAA,EAAkB,oBAAA;AAAA,EAClB,iBAAA,EAAmB,qBAAA;AAAA,EACnB,qBAAA,EAAuB;AACzB","file":"index.mjs","sourcesContent":["/**\n * AIP-14 governance tools — static `defineTool` handles wrapping the\n * `@agentproto/governance-engine` helpers.\n *\n * Each tool is a single global handle that reads `governanceConfig`\n * from the per-call context (validated by its `contextSchema`). One\n * handle serves any number of workspaces / tenants — adapters wire the\n * config in at invocation time via `resolveContext`.\n *\n * Adapters in `@agentproto/adapter-mastra` (and future `@agentproto/adapter-langchain`,\n * `@agentproto/adapter-a2a`) consume these handles and project them into their\n * native tool surface.\n */\n\nimport { signArtifactTool } from \"./sign-artifact.tool.js\"\nimport { recordAuditEventTool } from \"./record-audit-event.tool.js\"\nimport { requestSignaturesTool } from \"./request-signatures.tool.js\"\nimport { listPendingSignaturesTool } from \"./list-pending-signatures.tool.js\"\n\nexport {\n  signArtifactTool,\n  recordAuditEventTool,\n  requestSignaturesTool,\n  listPendingSignaturesTool,\n}\n\nexport const governanceTools = {\n  signArtifact: signArtifactTool,\n  recordAuditEvent: recordAuditEventTool,\n  requestSignatures: requestSignaturesTool,\n  listPendingSignatures: listPendingSignaturesTool,\n} as const\n\nexport type GovernanceToolBundle = typeof governanceTools\n"]}

package/dist/workspace-config-vgR1Ieoo.d.ts

@@ -0,0 +1,97 @@
+/**
+ * IGovernanceFilesystem — vendor-neutral filesystem interface used by the
+ * governance runtime. Lets a consumer plug a non-Node backend (Supabase
+ * Storage, S3, in-memory) without forking the runtime.
+ *
+ * All paths are absolute (the runtime resolves root-relative paths via
+ * `resolveFromRoot` before calling FS methods).
+ *
+ * Default implementation: `NodeGovernanceFilesystem`, backed by `node:fs`.
+ * Backends MUST guarantee:
+ *   - `writeFileAtomic` is atomic on same-volume rename (or equivalent).
+ *   - `appendLine` is durable across process crashes (line either fully
+ *     present or absent in the resulting file — no torn writes).
+ *   - `readFile` returns `null` (not throws) when the file does not exist.
+ */
+/** A single child entry returned by `listDirectory`. */
+interface DirectoryEntry {
+    /** File or subdirectory name (relative to the parent). No leading slash. */
+    name: string;
+    /** True for subdirectories, false for files. */
+    isDirectory: boolean;
+}
+interface IGovernanceFilesystem {
+    /** Recursively create a directory if it does not exist. */
+    ensureDir(absDir: string): Promise<void>;
+    /** Read a UTF-8 file. Returns `null` when the file does not exist. */
+    readFile(absPath: string): Promise<string | null>;
+    /**
+     * Atomically write the full contents of a file. Implementations should
+     * write to a temp file in the same dir, then rename — or use whatever
+     * atomic-replace primitive the backend provides.
+     */
+    writeFileAtomic(absPath: string, content: string): Promise<void>;
+    /**
+     * Append a single line + newline. Creates the file if absent. Must be
+     * crash-safe: a partially-written line MUST NOT be visible to a
+     * concurrent reader.
+     */
+    appendLine(absPath: string, line: string): Promise<void>;
+    /**
+     * List the immediate children of a directory. Returns `[]` when the
+     * directory does not exist (NOT throw). Order is implementation-defined;
+     * callers MUST sort if they need stable order.
+     */
+    listDirectory(absDir: string): Promise<DirectoryEntry[]>;
+}
+declare class NodeGovernanceFilesystem implements IGovernanceFilesystem {
+    ensureDir(absDir: string): Promise<void>;
+    readFile(absPath: string): Promise<string | null>;
+    writeFileAtomic(absPath: string, content: string): Promise<void>;
+    appendLine(absPath: string, line: string): Promise<void>;
+    listDirectory(absDir: string): Promise<DirectoryEntry[]>;
+}
+/** Default singleton — Node fs. */
+declare function defaultGovernanceFilesystem(): IGovernanceFilesystem;
+
+/**
+ * GovernanceConfig — runtime configuration the FS-only services need.
+ *
+ * Apps resolve genesis seed + HMAC secret from a vault / secrets manager and
+ * pass an instance into the runtime services. The package itself does NOT
+ * read environment variables or secret stores — it stays portable.
+ */
+
+interface GovernanceConfig {
+    /** Absolute path to the workspace root. */
+    workspaceRoot: string;
+    /** Hex-encoded 64-char workspace genesis seed. */
+    genesisSeed: string;
+    /** HMAC secret used for chain signatures. */
+    hmacSecret: string;
+    /**
+     * Filesystem adapter. Defaults to `NodeGovernanceFilesystem` (node:fs)
+     * when omitted. Apps with non-POSIX storage (Supabase Storage, S3,
+     * in-memory test fixtures) supply a custom implementation here.
+     */
+    filesystem?: IGovernanceFilesystem;
+    /** Optional: invoked when an audit-log line crosses an anchor threshold. */
+    anchorSink?: AnchorSink;
+    /** Anchor every N lines (default 1000). */
+    anchorEveryLines?: number;
+}
+interface AnchorPayload {
+    /** Audit-log file path (workspace-relative). */
+    logPath: string;
+    /** 0-based line index that triggered the anchor (the line that crossed the threshold). */
+    lineIndex: number;
+    /** The signature at that line — what gets anchored. */
+    signature: string;
+    /** ISO timestamp when the anchor was emitted. */
+    emittedAt: string;
+}
+type AnchorSink = (payload: AnchorPayload) => Promise<void>;
+/** Default anchor cadence. */
+declare const DEFAULT_ANCHOR_EVERY_LINES = 1000;
+
+export { type AnchorPayload as A, DEFAULT_ANCHOR_EVERY_LINES as D, type GovernanceConfig as G, type IGovernanceFilesystem as I, NodeGovernanceFilesystem as N, type AnchorSink as a, type DirectoryEntry as b, defaultGovernanceFilesystem as d };

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@agentproto/governance-engine",
+  "version": "0.1.0",
+  "description": "agentgovernance/v1 reference engine — record audit events, sign artifacts, maintain pending-signatures index. Vendor-neutral via the IGovernanceFilesystem interface (Node fs default, plug Supabase / S3 / in-memory adapters via the same interface). Pairs with @agentproto/governance for doctype types and validators.",
+  "keywords": [
+    "agentgovernance",
+    "governance",
+    "audit-log",
+    "hash-chain",
+    "signature",
+    "filesystem-adapter",
+    "engine",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/gov-1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/governance/engine"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.mjs",
+      "default": "./dist/tools/index.mjs"
+    },
+    "./provider": {
+      "types": "./dist/provider/index.d.ts",
+      "import": "./dist/provider/index.mjs",
+      "default": "./dist/provider/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@agentproto/driver": "0.1.0",
+    "@agentproto/governance": "0.1.0-alpha.0",
+    "@agentproto/ref": "0.1.0-alpha.0",
+    "@agentproto/tool": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}