@fulcrum_io/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to the Fulcrum TypeScript SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-12-26
+
+### Added
+- Initial release of Fulcrum TypeScript SDK
+- `FulcrumClient` class for connecting to Fulcrum gRPC server
+- `Envelope` class for workflow governance wrapping
+- Policy evaluation with `guard()` method
+- Event logging with `log()` method
+- TypeScript type definitions for all interfaces
+- Support for FAIL_OPEN and FAIL_CLOSED failure modes
+- Configurable timeout and API key authentication
+- Complete Protocol Buffer definitions included
+
+### Features
+- Real-time policy enforcement for AI agents
+- Cost tracking and budget management
+- Audit trail and compliance logging
+- Fail-safe error handling
+- Full TypeScript support with type definitions
+
+[0.1.0]: https://github.com/fulcrum-io/fulcrum/releases/tag/sdk-typescript-v0.1.0

package/LICENSE

@@ -0,0 +1,98 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship made available under the
+      License.
+
+      "Derivative Works" shall mean any work that is based on the Work.
+
+      "Contribution" shall mean any work of authorship submitted to the
+      Licensor for inclusion in the Work.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by Licensor.
+
+   2. Grant of Copyright License. Subject to the terms of this License,
+      each Contributor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable copyright license
+      to reproduce, prepare Derivative Works of, publicly display, publicly
+      perform, sublicense, and distribute the Work and such Derivative Works
+      in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms of this License,
+      each Contributor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable patent license
+      to make, have made, use, offer to sell, sell, import, and otherwise
+      transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work.
+
+   5. Submission of Contributions. Any Contribution intentionally
+      submitted for inclusion in the Work shall be under the terms of
+      this License.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. THE WORK IS PROVIDED "AS IS", WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. IN NO EVENT SHALL ANY CONTRIBUTOR BE
+      LIABLE FOR DAMAGES ARISING FROM USE OF THE WORK.
+
+   9. Accepting Warranty or Additional Liability. You may offer warranty
+      or additional liability obligations for a fee.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Fulcrum Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,94 @@
+# Fulcrum TypeScript SDK
+
+> Intelligent AI Governance for Enterprise Agents
+
+[![npm version](https://badge.fury.io/js/%40fulcrum-governance%2Fsdk.svg)](https://badge.fury.io/js/%40fulcrum-governance%2Fsdk)
+[![Node.js 18+](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+## Installation
+
+```bash
+npm install @fulcrum-governance/sdk
+```
+
+## Quick Start
+
+```typescript
+import { FulcrumClient } from '@fulcrum-governance/sdk';
+
+// Initialize client
+const client = new FulcrumClient({
+  host: 'your-fulcrum-server:50051',
+  apiKey: 'your-api-key',
+  onFailure: 'FAIL_OPEN' // or 'FAIL_CLOSED'
+});
+
+// Wrap agent executions in governance envelopes
+const envelope = client.envelope({
+  workflowId: 'customer-support-bot',
+  tenantId: 'your-tenant-id'
+});
+
+// Check if action is allowed before executing
+const allowed = await envelope.guard('send_email', userMessage);
+
+if (allowed) {
+  // Action approved - proceed
+  const result = await sendEmail(userMessage);
+  envelope.log('email_sent', { recipient: email, status: 'success' });
+} else {
+  // Action blocked by policy
+  envelope.log('action_blocked', { reason: 'policy_violation' });
+}
+```
+
+## Features
+
+- **Policy Enforcement**: Real-time governance checks before agent actions
+- **Cost Tracking**: Monitor and control LLM spending per workflow
+- **Audit Trail**: Complete execution history for compliance
+- **Fail-Safe Modes**: Configurable FAIL_OPEN or FAIL_CLOSED behavior
+- **TypeScript Support**: Full type definitions included
+
+## API Reference
+
+### FulcrumClient
+
+```typescript
+interface FulcrumClientOptions {
+  host: string;                      // gRPC server address (e.g., 'localhost:50051')
+  apiKey?: string;                   // Authentication key
+  onFailure?: 'FAIL_OPEN' | 'FAIL_CLOSED';  // Behavior on errors
+  timeoutMs?: number;                // Request timeout (default: 500ms)
+}
+```
+
+### Envelope
+
+```typescript
+interface EnvelopeOptions {
+  workflowId: string;                // Identifier for the workflow
+  executionId?: string;              // Auto-generated if not provided
+  tenantId?: string;                 // Defaults to 'default-tenant'
+  metadata?: Record<string, string>; // Additional context
+}
+```
+
+### Methods
+
+**`envelope.guard(actionName: string, inputText: string, metadata?: Record<string, string>): Promise<boolean>`**
+
+Checks if an action is allowed by current policies.
+
+**`envelope.log(eventType: string, payload: Record<string, any>): void`**
+
+Logs an event for audit trail and observability.
+
+## Documentation
+
+Full documentation: [https://docs.fulcrum.dev](https://docs.fulcrum.dev)
+
+## License
+
+Apache 2.0

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+export interface FulcrumClientOptions {
+    host: string;
+    apiKey?: string;
+    onFailure?: 'FAIL_OPEN' | 'FAIL_CLOSED';
+    timeoutMs?: number;
+}
+export interface EnvelopeOptions {
+    workflowId: string;
+    executionId?: string;
+    tenantId?: string;
+    metadata?: Record<string, string>;
+}
+export interface GuardResult {
+    allowed: boolean;
+    decision: string;
+    reason: string;
+}
+export declare class FulcrumClient {
+    private host;
+    private apiKey?;
+    private onFailure;
+    private timeoutMs;
+    private policyClient;
+    constructor(options: FulcrumClientOptions);
+    private initClients;
+    private getMetadata;
+    envelope(options: EnvelopeOptions): Envelope;
+    evaluatePolicy(context: {
+        tenantId: string;
+        workflowId: string;
+        inputText?: string;
+        attributes?: Record<string, string>;
+    }): Promise<GuardResult>;
+    shutdown(): void;
+}
+export declare class Envelope {
+    private client;
+    private executionId;
+    private tenantId;
+    private workflowId;
+    private envelopeId;
+    constructor(client: FulcrumClient, options: Required<EnvelopeOptions>);
+    guard(actionName: string, inputText?: string, metadata?: Record<string, string>): Promise<boolean>;
+    log(eventType: string, payload?: Record<string, any>): void;
+}
+export default FulcrumClient;

package/dist/index.js

@@ -0,0 +1,144 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Envelope = exports.FulcrumClient = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const uuid_1 = require("uuid");
+const path = __importStar(require("path"));
+class FulcrumClient {
+    constructor(options) {
+        this.host = options.host;
+        this.apiKey = options.apiKey;
+        this.onFailure = options.onFailure || 'FAIL_OPEN';
+        this.timeoutMs = options.timeoutMs || 500;
+        this.initClients();
+    }
+    initClients() {
+        // Proto files are in ../proto relative to dist/index.js
+        const protoPath = path.join(__dirname, '../proto');
+        const policyProto = protoLoader.loadSync(path.join(protoPath, 'fulcrum/policy/v1/policy_service.proto'), {
+            keepCase: true,
+            longs: String,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+            includeDirs: [protoPath] // Add includeDirs to resolve imports
+        });
+        const policyPackage = grpc.loadPackageDefinition(policyProto);
+        this.policyClient = new policyPackage.fulcrum.policy.v1.PolicyService(this.host, grpc.credentials.createInsecure());
+    }
+    getMetadata() {
+        const metadata = new grpc.Metadata();
+        if (this.apiKey) {
+            metadata.add('x-api-key', this.apiKey);
+        }
+        return metadata;
+    }
+    envelope(options) {
+        return new Envelope(this, {
+            ...options,
+            executionId: options.executionId || (0, uuid_1.v4)(),
+            tenantId: options.tenantId || 'default-tenant',
+            metadata: options.metadata || {},
+        });
+    }
+    async evaluatePolicy(context) {
+        return new Promise((resolve) => {
+            const deadline = new Date(Date.now() + this.timeoutMs);
+            this.policyClient.EvaluatePolicies(// Changed from EvaluatePolicy to EvaluatePolicies as per proto
+            {
+                context: {
+                    tenant_id: context.tenantId,
+                    workflow_id: context.workflowId,
+                    input_text: context.inputText,
+                    attributes: context.attributes
+                }
+            }, this.getMetadata(), { deadline }, (err, response) => {
+                if (err) {
+                    console.error('Policy evaluation failed:', err);
+                    if (this.onFailure === 'FAIL_OPEN') {
+                        resolve({ allowed: true, decision: 'ALLOW', reason: `Fail-safe: ${err.message}` });
+                    }
+                    else {
+                        resolve({ allowed: false, decision: 'DENY', reason: `Fail-safe (Closed): ${err.message}` });
+                    }
+                }
+                else {
+                    // Mapping Logic from EvaluatePoliciesResponse
+                    // message EvaluatePoliciesResponse {
+                    //   repeated PolicyDecision decisions = 1;
+                    //   EvaluationDecision final_decision = 2; // ALLOW, DENY, ...
+                    // }
+                    const isAllowed = response.final_decision === 'EVALUATION_DECISION_ALLOW' || response.final_decision === 'ALLOW'; // Check enum string mapping
+                    resolve({
+                        allowed: isAllowed,
+                        decision: response.final_decision,
+                        reason: "Policy Evaluation", // Response doesn't have top-level reason, maybe aggregate from decisions?
+                    });
+                }
+            });
+        });
+    }
+    shutdown() {
+        // Cleanup if needed
+    }
+}
+exports.FulcrumClient = FulcrumClient;
+class Envelope {
+    constructor(client, options) {
+        this.client = client;
+        this.executionId = options.executionId;
+        this.tenantId = options.tenantId;
+        this.workflowId = options.workflowId;
+        this.envelopeId = (0, uuid_1.v4)();
+    }
+    async guard(actionName, inputText = '', metadata) {
+        const result = await this.client.evaluatePolicy({
+            tenantId: this.tenantId,
+            workflowId: this.workflowId,
+            inputText,
+            attributes: { ...metadata, action: actionName },
+        });
+        return result.allowed;
+    }
+    log(eventType, payload = {}) {
+        // Async event logging - fire and forget
+        console.log(`[Fulcrum] ${this.envelopeId} | ${eventType}:`, payload);
+        // TODO: Implement actual event publishing
+    }
+}
+exports.Envelope = Envelope;
+exports.default = FulcrumClient;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@fulcrum_io/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Fulcrum - Intelligent AI Governance Platform",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["ai", "governance", "llm", "agents", "safety", "grpc"],
+  "author": "Fulcrum Team <hello@fulcrum.dev>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fulcrum-io/fulcrum.git",
+    "directory": "sdk/typescript"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.9.0",
+    "@grpc/proto-loader": "^0.7.0",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/uuid": "^9.0.0",
+    "typescript": "^5.3.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "eslint": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/",
+    "proto/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ]
+}

package/proto/events.proto

@@ -0,0 +1,197 @@
+syntax = "proto3";
+
+package fulcrum.events.v1;
+
+option go_package = "github.com/fulcrum-io/fulcrum/pkg/events/v1";
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/struct.proto";
+
+// FulcrumEvent is the normalized event schema.
+// All adapters emit events in this format regardless of framework.
+message FulcrumEvent {
+  // Event identification
+  string event_id = 1;
+  string envelope_id = 2;
+  string tenant_id = 14;
+  string workflow_id = 15;
+  google.protobuf.Timestamp timestamp = 3;
+  
+  // Event classification
+  EventType event_type = 4;
+  EventSeverity severity = 5;
+  
+  // Token tracking (present for LLM events)
+  TokenInfo tokens = 6;
+  
+  // Checkpoint reference (present for checkpoint events)
+  CheckpointRef checkpoint = 7;
+  
+  // Error information (present for error events)
+  ErrorInfo error = 8;
+  
+  // Tool invocation details (present for tool events)
+  ToolInfo tool = 9;
+  
+  // Policy evaluation result (present for policy events)
+  PolicyResult policy = 10;
+  
+  // Budget status (present for budget events)
+  BudgetStatusEvent budget = 11;
+  
+  // Framework-specific payload (opaque to control plane)
+  google.protobuf.Struct native_payload = 12;
+  
+  // Trace context for distributed tracing
+  TraceContext trace = 13;
+}
+
+// EventType categorizes the event
+enum EventType {
+  EVENT_TYPE_UNSPECIFIED = 0;
+  
+  // Execution lifecycle
+  EVENT_TYPE_EXECUTION_STARTED = 1;
+  EVENT_TYPE_EXECUTION_COMPLETED = 2;
+  EVENT_TYPE_EXECUTION_FAILED = 3;
+  EVENT_TYPE_EXECUTION_PAUSED = 4;
+  EVENT_TYPE_EXECUTION_RESUMED = 5;
+  EVENT_TYPE_EXECUTION_TERMINATED = 6;
+  
+  // LLM interactions
+  EVENT_TYPE_LLM_CALL_STARTED = 10;
+  EVENT_TYPE_LLM_CALL_COMPLETED = 11;
+  EVENT_TYPE_LLM_CALL_FAILED = 12;
+  EVENT_TYPE_LLM_STREAMING_CHUNK = 13;
+  
+  // Tool interactions
+  EVENT_TYPE_TOOL_INVOKED = 20;
+  EVENT_TYPE_TOOL_COMPLETED = 21;
+  EVENT_TYPE_TOOL_FAILED = 22;
+  
+  // Checkpointing
+  EVENT_TYPE_CHECKPOINT_CREATED = 30;
+  EVENT_TYPE_CHECKPOINT_RESTORED = 31;
+  
+  // Budget events
+  EVENT_TYPE_BUDGET_WARNING = 40;    // 80% threshold
+  EVENT_TYPE_BUDGET_EXCEEDED = 41;
+  EVENT_TYPE_BUDGET_RESET = 42;
+  
+  // Policy events
+  EVENT_TYPE_POLICY_EVALUATED = 50;
+  EVENT_TYPE_POLICY_VIOLATION = 51;
+  EVENT_TYPE_POLICY_WARNING = 52;
+  
+  // Agent coordination (multi-agent)
+  EVENT_TYPE_AGENT_HANDOFF = 60;
+  EVENT_TYPE_AGENT_SPAWN = 61;
+  EVENT_TYPE_AGENT_JOIN = 62;
+  
+  // Custom events
+  EVENT_TYPE_CUSTOM = 99;
+}
+
+// EventSeverity for filtering and alerting
+enum EventSeverity {
+  EVENT_SEVERITY_UNSPECIFIED = 0;
+  EVENT_SEVERITY_DEBUG = 1;
+  EVENT_SEVERITY_INFO = 2;
+  EVENT_SEVERITY_WARNING = 3;
+  EVENT_SEVERITY_ERROR = 4;
+  EVENT_SEVERITY_CRITICAL = 5;
+}
+
+// TokenInfo captures LLM token consumption
+message TokenInfo {
+  string model_id = 1;
+  int64 input_tokens = 2;
+  int64 output_tokens = 3;
+  double cost_usd = 4;
+  
+  // Latency metrics
+  int64 time_to_first_token_ms = 5;
+  int64 total_latency_ms = 6;
+  
+  // For streaming responses
+  bool is_streaming = 7;
+  int32 chunk_index = 8;
+}
+
+// CheckpointRef references a checkpoint
+message CheckpointRef {
+  string checkpoint_id = 1;
+  string state_hash = 2;
+  int64 size_bytes = 3;
+}
+
+// ErrorInfo captures error details
+message ErrorInfo {
+  string code = 1;
+  string message = 2;
+  bool recoverable = 3;
+  string stack_trace = 4;
+  
+  // Retry information
+  int32 retry_count = 5;
+  bool will_retry = 6;
+}
+
+// ToolInfo captures tool invocation details
+message ToolInfo {
+  string tool_name = 1;
+  string tool_id = 2;
+  
+  // Input/output (sanitized for logging)
+  google.protobuf.Struct input = 3;
+  google.protobuf.Struct output = 4;
+  
+  // Execution metrics
+  int64 latency_ms = 5;
+  bool success = 6;
+}
+
+// PolicyResult captures policy evaluation
+message PolicyResult {
+  string policy_id = 1;
+  string rule_id = 2;
+  PolicyDecision decision = 3;
+  string reason = 4;
+  
+  // What triggered the evaluation
+  string trigger = 5;
+}
+
+enum PolicyDecision {
+  POLICY_DECISION_UNSPECIFIED = 0;
+  POLICY_DECISION_ALLOW = 1;
+  POLICY_DECISION_DENY = 2;
+  POLICY_DECISION_WARN = 3;
+}
+
+// BudgetStatusEvent captures budget state for events
+message BudgetStatusEvent {
+  string budget_id = 1;
+  
+  // Current consumption
+  int64 tokens_used = 2;
+  int64 tokens_remaining = 3;
+  double cost_used_usd = 4;
+  double cost_remaining_usd = 5;
+  
+  // Percentage used
+  double percentage_used = 6;
+  
+  // Threshold that triggered this event
+  double threshold_percentage = 7;
+}
+
+// TraceContext for distributed tracing (W3C Trace Context compatible)
+message TraceContext {
+  string trace_id = 1;
+  string span_id = 2;
+  string parent_span_id = 3;
+  
+  // Baggage for cross-service context
+  map<string, string> baggage = 4;
+}