@valence-ai/sdk 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# Valence SDK
+
+The Valence SDK adds pre-execution policy enforcement to tool-using applications.
+
+It sends tool execution requests to Valence before the tool runs and returns one of three outcomes:
+
+- `ALLOW`
+- `BLOCK`
+- `REQUIRES_APPROVAL`
+
+Use it at the tool execution boundary in your application or agent runtime.
+
+## Package
+
+- Package name: `@valence-ai/sdk`
+
+## Install
+
+```bash
+npm install @valence-ai/sdk
+```
+
+## Environment variables
+
+```env
+VALENCE_API_BASE_URL=http://localhost:3000
+VALENCE_API_KEY=valence_pk_...
+VALENCE_WORKSPACE_ID=workspace-id
+VALENCE_PROJECT_ID=project-id
+VALENCE_AGENT_NAME=incidentos-agent
+VALENCE_ENVIRONMENT=staging
+```
+
+## Create a client
+
+```ts
+import { createValenceClient } from '@valence-ai/sdk';
+
+const client = createValenceClient({
+  baseUrl: process.env.VALENCE_API_BASE_URL!,
+  apiKey: process.env.VALENCE_API_KEY!,
+});
+```
+
+## Guard a tool dispatcher
+
+This is the recommended integration model for real applications.
+
+```ts
+import { createToolExecutionGuard } from '@valence-ai/sdk';
+
+const guard = createToolExecutionGuard(client, {
+  workspaceId: process.env.VALENCE_WORKSPACE_ID!,
+  projectId: process.env.VALENCE_PROJECT_ID!,
+  agentName: process.env.VALENCE_AGENT_NAME!,
+  environment: process.env.VALENCE_ENVIRONMENT as 'production' | 'staging' | 'sandbox',
+  goal: 'resolve_incident',
+  sessionId: 'session-123',
+});
+```
+
+## Run a guarded tool
+
+```ts
+const result = await guard.runTool(
+  {
+    tool: 'restart_service',
+    action: 'write',
+    parameters: { service: 'payments-api' },
+  },
+  async () => {
+    return restartService('payments-api');
+  }
+);
+```
+
+## Use `withValenceGuard` for a single tool
+
+```ts
+import { withValenceGuard } from '@valence-ai/sdk';
+
+const guardedReadIncident = withValenceGuard(client, {
+  workspaceId: process.env.VALENCE_WORKSPACE_ID!,
+  projectId: process.env.VALENCE_PROJECT_ID!,
+  agentName: process.env.VALENCE_AGENT_NAME!,
+  tool: 'read_incident',
+  action: 'read',
+  environment: 'staging',
+  goal: 'resolve_incident',
+});
+
+const incident = await guardedReadIncident(async () => {
+  return readIncident('INC-1421');
+});
+```
+
+## Request contract
+
+```ts
+type ToolEvent = {
+  agentId?: string;
+  agentName: string;
+  projectId?: string;
+  tool: string;
+  action: string;
+  environment: 'production' | 'staging' | 'sandbox';
+  goal: string;
+  sessionId?: string;
+  workspaceId?: string;
+  parameters?: Record<string, unknown>;
+  dryRun?: boolean;
+  timestamp?: string;
+};
+```
+
+## Decision response
+
+```ts
+type DecisionResponse = {
+  decision: 'ALLOW' | 'BLOCK' | 'REQUIRES_APPROVAL';
+  reason: string;
+  risk: 'LOW' | 'MEDIUM' | 'HIGH';
+  policyId: string | null;
+  approvalId: string | null;
+  latencyMs: number;
+};
+```
+
+## Runtime behavior
+
+- normal requests go to `/api/decide`
+- `dryRun: true` goes to `/api/simulate`
+- `ALLOW` executes the wrapped tool
+- `BLOCK` throws `ValenceBlockError` before execution
+- `REQUIRES_APPROVAL` throws `ValenceApprovalRequiredError` before execution
+
+Approval-required decisions are returned before execution so applications can route the request into an explicit review and retry workflow.
+
+## Error handling
+
+```ts
+import {
+  ValenceApprovalRequiredError,
+  ValenceBlockError,
+} from '@valence-ai/sdk';
+
+try {
+  await guard.runTool(
+    {
+      tool: 'restart_service',
+      action: 'write',
+      parameters: { service: 'payments-api' },
+    },
+    async () => restartService('payments-api')
+  );
+} catch (error) {
+  if (error instanceof ValenceApprovalRequiredError) {
+    console.log('Approval required:', error.message, error.approvalId);
+  } else if (error instanceof ValenceBlockError) {
+    console.log('Blocked:', error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+## Dry-run example
+
+```ts
+const decision = await guard.runTool(
+  {
+    tool: 'rollback_deployment',
+    action: 'write',
+    parameters: { service: 'checkout-api' },
+    dryRun: true,
+  },
+  async () => ({ simulated: true })
+);
+```
+
+Use dry-run when you want to preview the policy outcome without committing to a real operation.
+
+## Exported API
+
+```ts
+createValenceClient
+createToolExecutionGuard
+guardToolExecution
+withValenceGuard
+ValenceDecisionError
+ValenceBlockError
+ValenceApprovalRequiredError
+isValenceDecisionError
+```

package/dist/client.d.ts

@@ -0,0 +1,5 @@
+import type { DecisionResponse, ToolEvent, ValenceClientOptions } from './types.js';
+export declare function createValenceClient(options: ValenceClientOptions): {
+    decide(event: ToolEvent): Promise<DecisionResponse>;
+};
+//# 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,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEpF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB;kBAMrC,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC;EAwChE"}

package/dist/client.js

@@ -0,0 +1,41 @@
+export function createValenceClient(options) {
+    const request = options.fetch ?? fetch;
+    const decidePath = options.decidePath ?? '/api/decide';
+    const simulatePath = options.simulatePath ?? '/api/simulate';
+    return {
+        async decide(event) {
+            const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+            const timeout = controller && options.timeoutMs
+                ? setTimeout(() => controller.abort(), options.timeoutMs)
+                : null;
+            try {
+                const path = event.dryRun ? simulatePath : decidePath;
+                const response = await request(`${options.baseUrl}${path}`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-api-key': options.apiKey,
+                        ...options.headers,
+                    },
+                    signal: controller?.signal,
+                    body: JSON.stringify({
+                        ...event,
+                        timestamp: event.timestamp ?? new Date().toISOString(),
+                        dryRun: event.dryRun ?? false,
+                        parameters: event.parameters ?? {},
+                    }),
+                });
+                if (!response.ok) {
+                    throw new Error(`Valence decision request failed with ${response.status}`);
+                }
+                return (await response.json());
+            }
+            finally {
+                if (timeout) {
+                    clearTimeout(timeout);
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC7D,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,aAAa,CAAC;IACvD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,eAAe,CAAC;IAE7D,OAAO;QACH,KAAK,CAAC,MAAM,CAAC,KAAgB;YACzB,MAAM,UAAU,GACZ,OAAO,eAAe,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YAC1E,MAAM,OAAO,GACT,UAAU,IAAI,OAAO,CAAC,SAAS;gBAC3B,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,SAAS,CAAC;gBACzD,CAAC,CAAC,IAAI,CAAC;YAEf,IAAI,CAAC;gBACD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC;gBACtD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;oBACxD,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE;wBACL,cAAc,EAAE,kBAAkB;wBAClC,WAAW,EAAE,OAAO,CAAC,MAAM;wBAC3B,GAAG,OAAO,CAAC,OAAO;qBACrB;oBACD,MAAM,EAAE,UAAU,EAAE,MAAM;oBAC1B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACjB,GAAG,KAAK;wBACR,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;wBACtD,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,KAAK;wBAC7B,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE;qBACrC,CAAC;iBACL,CAAC,CAAC;gBAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;oBACf,MAAM,IAAI,KAAK,CACX,wCAAwC,QAAQ,CAAC,MAAM,EAAE,CAC5D,CAAC;gBACN,CAAC;gBAED,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAqB,CAAC;YACvD,CAAC;oBAAS,CAAC;gBACP,IAAI,OAAO,EAAE,CAAC;oBACV,YAAY,CAAC,OAAO,CAAC,CAAC;gBAC1B,CAAC;YACL,CAAC;QACL,CAAC;KACJ,CAAC;AACN,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+import type { DecisionResponse, ToolEvent } from './types.js';
+export declare class ValenceDecisionError extends Error {
+    readonly decision: DecisionResponse['decision'];
+    readonly risk: DecisionResponse['risk'];
+    readonly policyId: string | null;
+    readonly approvalId: string | null;
+    readonly latencyMs: number;
+    readonly event: ToolEvent;
+    constructor(message: string, decision: DecisionResponse, event: ToolEvent);
+}
+export declare class ValenceBlockError extends ValenceDecisionError {
+    constructor(decision: DecisionResponse, event: ToolEvent);
+}
+export declare class ValenceApprovalRequiredError extends ValenceDecisionError {
+    constructor(decision: DecisionResponse, event: ToolEvent);
+}
+export declare function isValenceDecisionError(error: unknown): error is ValenceDecisionError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE9D,qBAAa,oBAAqB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS;CAU5E;AAED,qBAAa,iBAAkB,SAAQ,oBAAoB;gBAC3C,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS;CAI3D;AAED,qBAAa,4BAA6B,SAAQ,oBAAoB;gBACtD,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS;CAQ3D;AAED,wBAAgB,sBAAsB,CAClC,KAAK,EAAE,OAAO,GACf,KAAK,IAAI,oBAAoB,CAE/B"}

package/dist/errors.js

@@ -0,0 +1,28 @@
+export class ValenceDecisionError extends Error {
+    constructor(message, decision, event) {
+        super(message);
+        this.name = 'ValenceDecisionError';
+        this.decision = decision.decision;
+        this.risk = decision.risk;
+        this.policyId = decision.policyId;
+        this.approvalId = decision.approvalId;
+        this.latencyMs = decision.latencyMs;
+        this.event = event;
+    }
+}
+export class ValenceBlockError extends ValenceDecisionError {
+    constructor(decision, event) {
+        super(decision.reason, decision, event);
+        this.name = 'ValenceBlockError';
+    }
+}
+export class ValenceApprovalRequiredError extends ValenceDecisionError {
+    constructor(decision, event) {
+        super(`${decision.reason} Approval id: ${decision.approvalId ?? 'pending'}`, decision, event);
+        this.name = 'ValenceApprovalRequiredError';
+    }
+}
+export function isValenceDecisionError(error) {
+    return error instanceof ValenceDecisionError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAQ3C,YAAY,OAAe,EAAE,QAA0B,EAAE,KAAgB;QACrE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAClC,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;CACJ;AAED,MAAM,OAAO,iBAAkB,SAAQ,oBAAoB;IACvD,YAAY,QAA0B,EAAE,KAAgB;QACpD,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IACpC,CAAC;CACJ;AAED,MAAM,OAAO,4BAA6B,SAAQ,oBAAoB;IAClE,YAAY,QAA0B,EAAE,KAAgB;QACpD,KAAK,CACD,GAAG,QAAQ,CAAC,MAAM,iBAAiB,QAAQ,CAAC,UAAU,IAAI,SAAS,EAAE,EACrE,QAAQ,EACR,KAAK,CACR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC/C,CAAC;CACJ;AAED,MAAM,UAAU,sBAAsB,CAClC,KAAc;IAEd,OAAO,KAAK,YAAY,oBAAoB,CAAC;AACjD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createValenceClient } from './client.js';
+export { createToolExecutionGuard, guardToolExecution, withValenceGuard, } from './wrap-tool.js';
+export { ValenceApprovalRequiredError, ValenceBlockError, ValenceDecisionError, isValenceDecisionError, } from './errors.js';
+export type { DecisionResponse, ToolDefinition, ToolEvent, ToolExecutionContext, ToolExecutionHooks, ToolExecutionRequest, ToolParameters, ValenceClientOptions, ValenceDecision, ValenceEnvironment, ValenceRisk, } 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,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACH,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACH,4BAA4B,EAC5B,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,GACzB,MAAM,aAAa,CAAC;AACrB,YAAY,EACR,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,WAAW,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createValenceClient } from './client.js';
+export { createToolExecutionGuard, guardToolExecution, withValenceGuard, } from './wrap-tool.js';
+export { ValenceApprovalRequiredError, ValenceBlockError, ValenceDecisionError, isValenceDecisionError, } from './errors.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,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACH,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACH,4BAA4B,EAC5B,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,GACzB,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+export type ValenceDecision = 'ALLOW' | 'BLOCK' | 'REQUIRES_APPROVAL';
+export type ValenceRisk = 'LOW' | 'MEDIUM' | 'HIGH';
+export type ValenceEnvironment = 'production' | 'staging' | 'sandbox';
+export type ToolParameters = Record<string, unknown>;
+export type ToolEvent = {
+    agentId?: string;
+    agentName: string;
+    projectId?: string;
+    tool: string;
+    action: string;
+    environment: ValenceEnvironment;
+    goal: string;
+    sessionId?: string;
+    workspaceId?: string;
+    parameters?: ToolParameters;
+    dryRun?: boolean;
+    timestamp?: string;
+};
+export type DecisionResponse = {
+    decision: ValenceDecision;
+    reason: string;
+    risk: ValenceRisk;
+    policyId: string | null;
+    approvalId: string | null;
+    latencyMs: number;
+};
+export type ToolExecutionContext = Omit<ToolEvent, 'tool' | 'action' | 'parameters' | 'timestamp'>;
+export type ToolDefinition = {
+    tool: string;
+    action: string;
+    parameters?: ToolParameters;
+};
+export type ToolExecutionRequest = ToolExecutionContext & ToolDefinition;
+export type ToolExecutionHooks<T> = {
+    onDecision?: (decision: DecisionResponse, event: ToolEvent) => void | Promise<void>;
+    onAllow?: (decision: DecisionResponse, event: ToolEvent) => void | Promise<void>;
+    onBlock?: (decision: DecisionResponse, event: ToolEvent) => void | Promise<void>;
+    onApprovalRequired?: (decision: DecisionResponse, event: ToolEvent) => void | Promise<void>;
+    onExecuted?: (result: T, decision: DecisionResponse, event: ToolEvent) => void | Promise<void>;
+};
+export type ValenceFetch = typeof fetch;
+export type ValenceClientOptions = {
+    baseUrl: string;
+    apiKey: string;
+    fetch?: ValenceFetch;
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+    decidePath?: string;
+    simulatePath?: string;
+};
+//# 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,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,mBAAmB,CAAC;AACtE,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AACpD,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AACtE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,kBAAkB,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC3B,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACnC,SAAS,EACT,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,WAAW,CACjD,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,cAAc,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AAEzE,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAChC,UAAU,CAAC,EAAE,CACT,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,SAAS,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF,kBAAkB,CAAC,EAAE,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,SAAS,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,UAAU,CAAC,EAAE,CACT,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,SAAS,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,OAAO,KAAK,CAAC;AAExC,MAAM,MAAM,oBAAoB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+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":""}

package/dist/wrap-tool.d.ts

@@ -0,0 +1,12 @@
+import type { ToolEvent, ToolExecutionContext, ToolExecutionHooks, ToolExecutionRequest } from './types.js';
+import { createValenceClient } from './client.js';
+type ValenceClient = ReturnType<typeof createValenceClient>;
+export declare function guardToolExecution<T>(client: ValenceClient, request: ToolExecutionRequest, execute: () => Promise<T>, hooks?: ToolExecutionHooks<T>): Promise<T>;
+export declare function createToolExecutionGuard(client: ValenceClient, context: ToolExecutionContext, hooks?: ToolExecutionHooks<unknown>): {
+    runTool: <T>(request: Omit<ToolExecutionRequest, keyof ToolExecutionContext>, execute: () => Promise<T>, runtimeHooks?: ToolExecutionHooks<T>) => Promise<T>;
+    wrapTool<T>(request: Omit<ToolExecutionRequest, keyof ToolExecutionContext>, execute: () => Promise<T>, runtimeHooks?: ToolExecutionHooks<T>): () => Promise<T>;
+};
+export type ValenceGuardOptions = ToolEvent;
+export declare function withValenceGuard(client: ValenceClient, event: ValenceGuardOptions): <T>(toolFn: () => Promise<T>, hooks?: ToolExecutionHooks<T>) => Promise<T>;
+export {};
+//# sourceMappingURL=wrap-tool.d.ts.map

package/dist/wrap-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-tool.d.ts","sourceRoot":"","sources":["../src/wrap-tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAER,SAAS,EACT,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAsB5D,wBAAsB,kBAAkB,CAAC,CAAC,EACtC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,KAAK,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,cAsBhC;AAED,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,oBAAoB,EAC7B,KAAK,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC;cAEZ,CAAC,WACX,IAAI,CAAC,oBAAoB,EAAE,MAAM,oBAAoB,CAAC,WACtD,MAAM,OAAO,CAAC,CAAC,CAAC,iBACV,kBAAkB,CAAC,CAAC,CAAC;aAmB3B,CAAC,WACG,IAAI,CAAC,oBAAoB,EAAE,MAAM,oBAAoB,CAAC,WACtD,MAAM,OAAO,CAAC,CAAC,CAAC,iBACV,kBAAkB,CAAC,CAAC,CAAC;EAK/C;AAED,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAE5C,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,mBAAmB,IAEW,CAAC,EAClC,QAAQ,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,QAAQ,kBAAkB,CAAC,CAAC,CAAC,gBAIpC"}

package/dist/wrap-tool.js

@@ -0,0 +1,54 @@
+import { ValenceApprovalRequiredError, ValenceBlockError } from './errors.js';
+async function applyHooks(hooks, decision, event) {
+    await hooks?.onDecision?.(decision, event);
+    if (decision.decision === 'ALLOW') {
+        await hooks?.onAllow?.(decision, event);
+        return;
+    }
+    if (decision.decision === 'REQUIRES_APPROVAL') {
+        await hooks?.onApprovalRequired?.(decision, event);
+        return;
+    }
+    await hooks?.onBlock?.(decision, event);
+}
+export async function guardToolExecution(client, request, execute, hooks) {
+    const event = {
+        ...request,
+        parameters: request.parameters ?? {},
+        dryRun: request.dryRun ?? false,
+    };
+    const decision = await client.decide(event);
+    await applyHooks(hooks, decision, event);
+    if (decision.decision === 'ALLOW') {
+        const result = await execute();
+        await hooks?.onExecuted?.(result, decision, event);
+        return result;
+    }
+    if (decision.decision === 'REQUIRES_APPROVAL') {
+        throw new ValenceApprovalRequiredError(decision, event);
+    }
+    throw new ValenceBlockError(decision, event);
+}
+export function createToolExecutionGuard(client, context, hooks) {
+    const runTool = async (request, execute, runtimeHooks) => {
+        return guardToolExecution(client, {
+            ...context,
+            ...request,
+        }, execute, {
+            ...hooks,
+            ...runtimeHooks,
+        });
+    };
+    return {
+        runTool,
+        wrapTool(request, execute, runtimeHooks) {
+            return () => runTool(request, execute, runtimeHooks);
+        },
+    };
+}
+export function withValenceGuard(client, event) {
+    return async function runGuardedTool(toolFn, hooks) {
+        return guardToolExecution(client, event, toolFn, hooks);
+    };
+}
+//# sourceMappingURL=wrap-tool.js.map

package/dist/wrap-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-tool.js","sourceRoot":"","sources":["../src/wrap-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAY9E,KAAK,UAAU,UAAU,CACrB,KAAwC,EACxC,QAA0B,EAC1B,KAAgB;IAEhB,MAAM,KAAK,EAAE,UAAU,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAE3C,IAAI,QAAQ,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChC,MAAM,KAAK,EAAE,OAAO,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACxC,OAAO;IACX,CAAC;IAED,IAAI,QAAQ,CAAC,QAAQ,KAAK,mBAAmB,EAAE,CAAC;QAC5C,MAAM,KAAK,EAAE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACnD,OAAO;IACX,CAAC;IAED,MAAM,KAAK,EAAE,OAAO,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACpC,MAAqB,EACrB,OAA6B,EAC7B,OAAyB,EACzB,KAA6B;IAE7B,MAAM,KAAK,GAAc;QACrB,GAAG,OAAO;QACV,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;KAClC,CAAC;IAEF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IAEzC,IAAI,QAAQ,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,OAAO,EAAE,CAAC;QAC/B,MAAM,KAAK,EAAE,UAAU,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC;IAClB,CAAC;IAED,IAAI,QAAQ,CAAC,QAAQ,KAAK,mBAAmB,EAAE,CAAC;QAC5C,MAAM,IAAI,4BAA4B,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,IAAI,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,wBAAwB,CACpC,MAAqB,EACrB,OAA6B,EAC7B,KAAmC;IAEnC,MAAM,OAAO,GAAG,KAAK,EACjB,OAA+D,EAC/D,OAAyB,EACzB,YAAoC,EACtC,EAAE;QACA,OAAO,kBAAkB,CACrB,MAAM,EACN;YACI,GAAG,OAAO;YACV,GAAG,OAAO;SACb,EACD,OAAO,EACP;YACI,GAAI,KAA2C;YAC/C,GAAG,YAAY;SAClB,CACJ,CAAC;IACN,CAAC,CAAC;IAEF,OAAO;QACH,OAAO;QAEP,QAAQ,CACJ,OAA+D,EAC/D,OAAyB,EACzB,YAAoC;YAEpC,OAAO,GAAG,EAAE,CAAC,OAAO,CAAI,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;QAC5D,CAAC;KACJ,CAAC;AACN,CAAC;AAID,MAAM,UAAU,gBAAgB,CAC5B,MAAqB,EACrB,KAA0B;IAE1B,OAAO,KAAK,UAAU,cAAc,CAChC,MAAwB,EACxB,KAA6B;QAE7B,OAAO,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5D,CAAC,CAAC;AACN,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@valence-ai/sdk",
+  "version": "0.1.0",
+  "description": "Pre-execution policy enforcement SDK for tool-using AI agents.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/praveensahu-dev/Valence-AI.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://www.valenceai.co",
+  "bugs": {
+    "url": "https://github.com/praveensahu-dev/Valence-AI/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "if exist dist rmdir /s /q dist",
+    "prepack": "npm run clean && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "sdk",
+    "security",
+    "tool-calling",
+    "guardrails",
+    "policy"
+  ]
+}