@felspar/sdk 0.0.0-stage → 0.1.1

package/dist/draft-action-gate-claude.js

@@ -0,0 +1,50 @@
+import {
+  entityIdOf,
+  jobOf
+} from "./chunks/chunk-6EZBI7O6.js";
+import "./chunks/chunk-C2VMKF3S.js";
+
+// src/draft-action-gate-claude.ts
+function felsparPreToolUse(gate) {
+  return async (input) => {
+    const toolName = input.tool_name ?? "";
+    if (input.hook_event_name !== "PreToolUse" || !gate.isGated(toolName)) {
+      return {};
+    }
+    const verdict = await gate.check(input.session_id, toolName, input.tool_input);
+    if (verdict.allow) {
+      return {};
+    }
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: `Felspar's gate: ${verdict.reason}`
+      }
+    };
+  };
+}
+function felsparPostToolUse(gate) {
+  return async (input) => {
+    const job = jobOf(input.tool_input);
+    if (job !== void 0 && input.hook_event_name === "PostToolUse" && gate.isOutputCheckTool(input.tool_name ?? "")) {
+      gate.decisions.recordOutputCheck(input.session_id, job, input.tool_response);
+    }
+    const entity = entityIdOf(input.tool_input);
+    if (entity !== void 0 && input.hook_event_name === "PostToolUse" && gate.isDecisionTool(input.tool_name ?? "")) {
+      gate.decisions.record(input.session_id, entity, input.tool_response);
+    }
+    return {};
+  };
+}
+function felsparHooks(gate) {
+  return {
+    PreToolUse: [{ hooks: [felsparPreToolUse(gate)] }],
+    PostToolUse: [{ hooks: [felsparPostToolUse(gate)] }]
+  };
+}
+export {
+  felsparHooks,
+  felsparPostToolUse,
+  felsparPreToolUse
+};

package/dist/draft-action-gate-eve.js

@@ -0,0 +1,53 @@
+import {
+  entityIdOf,
+  jobOf
+} from "./chunks/chunk-6EZBI7O6.js";
+import "./chunks/chunk-C2VMKF3S.js";
+
+// src/draft-action-gate-eve.ts
+function felsparGate(gate) {
+  return async (call) => {
+    if (!gate.isGated(call.toolName)) {
+      return "not-applicable";
+    }
+    const verdict = await gate.check(call.session.id, call.toolName, call.toolInput);
+    return { type: verdict.allow ? "approved" : "denied", reason: verdict.reason };
+  };
+}
+function felsparDecisionEvents(gate) {
+  const checks = /* @__PURE__ */ new Map();
+  function requested(event) {
+    const { actions } = event.data;
+    if (actions === void 0) {
+      return;
+    }
+    for (const action of actions) {
+      const entity = entityIdOf(action.input);
+      if (entity !== void 0 && gate.isDecisionTool(action.toolName ?? "")) {
+        gate.decisions.noteRequest(action.callId, entity);
+      }
+      const job = jobOf(action.input);
+      if (job !== void 0 && gate.isOutputCheckTool(action.toolName ?? "")) {
+        checks.set(action.callId, job);
+      }
+    }
+  }
+  function result(event, context) {
+    const action = event.data.result;
+    const job = action?.callId === void 0 ? void 0 : checks.get(action.callId);
+    if (job !== void 0 && action?.callId !== void 0) {
+      checks.delete(action.callId);
+      if (action.isError !== true) {
+        gate.decisions.recordOutputCheck(context.session.id, job, action.output);
+      }
+    }
+    if (action?.callId !== void 0 && gate.isDecisionTool(action.toolName ?? "") && action.isError !== true) {
+      gate.decisions.noteResult(context.session.id, action.callId, action.output);
+    }
+  }
+  return { "actions.requested": requested, "action.result": result };
+}
+export {
+  felsparDecisionEvents,
+  felsparGate
+};

package/dist/draft-action-gate-openai.js

@@ -0,0 +1,60 @@
+import {
+  entityIdOf,
+  jobOf
+} from "./chunks/chunk-6EZBI7O6.js";
+import "./chunks/chunk-C2VMKF3S.js";
+
+// src/draft-action-gate-openai.ts
+function argumentsOf(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function felsparToolInputGuardrail(gate, options) {
+  return {
+    type: "tool_input",
+    name: "felspar_action_gate",
+    async run(data) {
+      if (!gate.isGated(data.toolCall.name)) {
+        return { behavior: { type: "allow" } };
+      }
+      const input = argumentsOf(data.toolCall.arguments);
+      let verdict;
+      try {
+        verdict = await gate.check(options.sessionOf(data.context), data.toolCall.name, input);
+      } catch (error) {
+        verdict = { allow: false, reason: `gate error: ${String(error)}` };
+      }
+      return verdict.allow ? { behavior: { type: "allow" }, outputInfo: { reason: verdict.reason } } : {
+        behavior: {
+          type: "rejectContent",
+          message: `Felspar's gate denied this call: ${verdict.reason}`
+        }
+      };
+    }
+  };
+}
+function felsparDecisionOutputGuardrail(gate, options) {
+  return {
+    type: "tool_output",
+    name: "felspar_decisions",
+    async run(data) {
+      const input = argumentsOf(data.toolCall.arguments);
+      const job = jobOf(input);
+      if (job !== void 0 && gate.isOutputCheckTool(data.toolCall.name)) {
+        gate.decisions.recordOutputCheck(options.sessionOf(data.context), job, data.output);
+      }
+      const entity = entityIdOf(input);
+      if (entity !== void 0 && gate.isDecisionTool(data.toolCall.name)) {
+        gate.decisions.record(options.sessionOf(data.context), entity, data.output);
+      }
+      return { behavior: { type: "allow" } };
+    }
+  };
+}
+export {
+  felsparDecisionOutputGuardrail,
+  felsparToolInputGuardrail
+};

package/dist/draft-action-gate.js

@@ -0,0 +1,35 @@
+import {
+  checkAction,
+  createActionGate,
+  createDecisionRecorder,
+  decisionFromResult,
+  emailRecipientFields,
+  emailSubjectFields,
+  entityIdOf,
+  felsparOutputCheckVerifier,
+  felsparVerifier,
+  gatedRule,
+  isCompanyDomain,
+  jobOf,
+  outputCheckFromResult,
+  outputTextDigest,
+  sharedDomains
+} from "./chunks/chunk-6EZBI7O6.js";
+import "./chunks/chunk-C2VMKF3S.js";
+export {
+  checkAction,
+  createActionGate,
+  createDecisionRecorder,
+  decisionFromResult,
+  emailRecipientFields,
+  emailSubjectFields,
+  entityIdOf,
+  felsparOutputCheckVerifier,
+  felsparVerifier,
+  gatedRule,
+  isCompanyDomain,
+  jobOf,
+  outputCheckFromResult,
+  outputTextDigest,
+  sharedDomains
+};

package/dist/draft-hosted-client.js

@@ -0,0 +1,8 @@
+import {
+  FelsparRequestError,
+  createHostedFelsparClient
+} from "./chunks/chunk-C2VMKF3S.js";
+export {
+  FelsparRequestError,
+  createHostedFelsparClient
+};

package/dist/types/draft-action-gate-claude.d.ts

@@ -0,0 +1,27 @@
+import type { ActionGate } from "./draft-action-gate.js";
+interface HookInput {
+    hook_event_name: string;
+    session_id: string;
+    tool_name?: string;
+    tool_input?: unknown;
+    tool_response?: unknown;
+}
+export interface PreToolUseDecision {
+    hookSpecificOutput: {
+        hookEventName: "PreToolUse";
+        permissionDecision: "deny";
+        permissionDecisionReason: string;
+    };
+}
+type NoDecision = Record<string, never>;
+export declare function felsparPreToolUse(gate: ActionGate): (input: HookInput) => Promise<PreToolUseDecision | NoDecision>;
+export declare function felsparPostToolUse(gate: ActionGate): (input: HookInput) => Promise<NoDecision>;
+export declare function felsparHooks(gate: ActionGate): {
+    PreToolUse: {
+        hooks: ((input: HookInput) => Promise<PreToolUseDecision | NoDecision>)[];
+    }[];
+    PostToolUse: {
+        hooks: ((input: HookInput) => Promise<NoDecision>)[];
+    }[];
+};
+export {};

package/dist/types/draft-action-gate-decisions.d.ts

@@ -0,0 +1,36 @@
+import type { FelsparOutputCheck } from "./draft-action-gate-outputs.js";
+export interface FelsparDecision {
+    entity: string;
+    outcome: string;
+    executionObjectId: string;
+    receipt: {
+        receiptDigest: string;
+    } & Record<string, unknown>;
+    context: unknown;
+    evidenceFreshUntil?: string | null;
+}
+export interface VerifiedDecision {
+    jobId: string;
+    entityId: string;
+    releaseId?: string;
+    outcome: string | null;
+}
+export type ReceiptVerifier = (decision: FelsparDecision) => Promise<VerifiedDecision | null>;
+export declare function jobOf(input: unknown): string | undefined;
+export declare function entityIdOf(input: unknown): string | undefined;
+export declare function decisionFromResult(entity: string, output: unknown): FelsparDecision | null;
+export interface DecisionRecorder {
+    recordOutputCheck: (sessionId: string, jobId: string, output: unknown) => FelsparOutputCheck | null;
+    outputChecksIn: (sessionId: string) => readonly FelsparOutputCheck[];
+    record: (sessionId: string, entity: string, output: unknown) => FelsparDecision | null;
+    noteRequest: (callId: string, entity: string) => void;
+    noteResult: (sessionId: string, callId: string, output: unknown) => FelsparDecision | null;
+    decisionsIn: (sessionId: string) => readonly FelsparDecision[];
+    forget: (sessionId: string) => void;
+}
+export interface DecisionRecorderLimits {
+    sessions?: number;
+    decisionsPerSession?: number;
+    pendingRequests?: number;
+}
+export declare function createDecisionRecorder(limits?: DecisionRecorderLimits): DecisionRecorder;

package/dist/types/draft-action-gate-domains.d.ts

@@ -0,0 +1,2 @@
+export declare const sharedDomains: readonly string[];
+export declare function isCompanyDomain(entity: string, extraShared?: readonly string[]): boolean;

package/dist/types/draft-action-gate-eve.d.ts

@@ -0,0 +1,42 @@
+import type { ActionGate } from "./draft-action-gate.js";
+export type EveApprovalStatus = "not-applicable" | {
+    readonly type: "approved" | "denied";
+    readonly reason: string;
+};
+export declare function felsparGate(gate: ActionGate): (call: {
+    readonly session: {
+        readonly id: string;
+    };
+    readonly toolName: string;
+    readonly toolInput?: unknown;
+}) => Promise<EveApprovalStatus>;
+interface EveActionRequest {
+    readonly callId: string;
+    readonly toolName?: string | undefined;
+    readonly input?: unknown;
+}
+interface EveActionResult {
+    readonly callId?: string | undefined;
+    readonly toolName?: string | undefined;
+    readonly output?: unknown;
+    readonly isError?: boolean | undefined;
+}
+interface RequestedEvent {
+    readonly data: {
+        readonly actions?: readonly EveActionRequest[] | undefined;
+    };
+}
+interface ResultEvent {
+    readonly data: {
+        readonly result?: EveActionResult | undefined;
+    };
+}
+export declare function felsparDecisionEvents(gate: ActionGate): {
+    "actions.requested": (event: RequestedEvent) => void;
+    "action.result": (event: ResultEvent, context: {
+        readonly session: {
+            readonly id: string;
+        };
+    }) => void;
+};
+export {};

package/dist/types/draft-action-gate-openai.d.ts

@@ -0,0 +1,36 @@
+import type { ActionGate } from "./draft-action-gate.js";
+export type ToolGuardrailBehavior = {
+    type: "allow";
+} | {
+    type: "rejectContent";
+    message: string;
+};
+export interface ToolGuardrailOutput {
+    behavior: ToolGuardrailBehavior;
+    outputInfo?: unknown;
+}
+interface GuardrailData {
+    context: {
+        context?: unknown;
+    };
+    toolCall: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface OpenAIGuardrailOptions {
+    sessionOf: (context: GuardrailData["context"]) => string;
+}
+export declare function felsparToolInputGuardrail(gate: ActionGate, options: OpenAIGuardrailOptions): {
+    type: "tool_input";
+    name: string;
+    run(data: GuardrailData): Promise<ToolGuardrailOutput>;
+};
+export declare function felsparDecisionOutputGuardrail(gate: ActionGate, options: OpenAIGuardrailOptions): {
+    type: "tool_output";
+    name: string;
+    run(data: GuardrailData & {
+        output: unknown;
+    }): Promise<ToolGuardrailOutput>;
+};
+export {};

package/dist/types/draft-action-gate-outputs.d.ts

@@ -0,0 +1,35 @@
+export interface FelsparOutputCheck {
+    checkId: string;
+    jobId: string;
+    output: string;
+    status: string;
+    decisionReceiptDigest: string;
+    artifactDigest: string;
+    receiptDigest: string;
+}
+export type OutputCheckVerifier = (check: FelsparOutputCheck) => Promise<{
+    status: string;
+    receiptDigest: string | null;
+    artifactDigest: string | null;
+    decisionReceiptDigest: string;
+} | null>;
+export interface OutputCheckRule {
+    fields: readonly string[];
+    output?: string;
+}
+type JsonRecord = Record<string, unknown>;
+export declare function outputCheckFromResult(jobId: string, output: unknown): FelsparOutputCheck | null;
+export declare function outputTextDigest(value: string): Promise<string>;
+export declare function outputCheckProblem(rule: OutputCheckRule, call: {
+    input: JsonRecord;
+    decisionReceiptDigest: string;
+    checks: readonly FelsparOutputCheck[];
+    verify: OutputCheckVerifier | undefined;
+}): Promise<string | null>;
+export declare function felsparOutputCheckVerifier(configuration: {
+    origin: string;
+    agentKey?: string;
+    session?: string;
+    fetcher?: typeof fetch;
+}): OutputCheckVerifier;
+export {};

package/dist/types/draft-action-gate-verifier.d.ts

@@ -0,0 +1,7 @@
+import type { ReceiptVerifier } from "./draft-action-gate-decisions.js";
+export declare function felsparVerifier(configuration: {
+    origin: string;
+    agentKey?: string;
+    session?: string;
+    fetcher?: typeof fetch;
+}): ReceiptVerifier;

package/dist/types/draft-action-gate.d.ts

@@ -0,0 +1,65 @@
+import type { FelsparOutputCheck, OutputCheckRule, OutputCheckVerifier } from "./draft-action-gate-outputs.js";
+import type { DecisionRecorder, FelsparDecision, ReceiptVerifier } from "./draft-action-gate-decisions.js";
+export { createDecisionRecorder, decisionFromResult, entityIdOf, jobOf, } from "./draft-action-gate-decisions.js";
+export type { DecisionRecorder, DecisionRecorderLimits, FelsparDecision, ReceiptVerifier, VerifiedDecision, } from "./draft-action-gate-decisions.js";
+export { isCompanyDomain, sharedDomains } from "./draft-action-gate-domains.js";
+export { felsparVerifier } from "./draft-action-gate-verifier.js";
+export { felsparOutputCheckVerifier, outputCheckFromResult, outputTextDigest, } from "./draft-action-gate-outputs.js";
+export type { FelsparOutputCheck, OutputCheckRule, OutputCheckVerifier, } from "./draft-action-gate-outputs.js";
+export interface ActionRule {
+    outcomes: readonly string[];
+    fields: readonly string[];
+    recipientFields?: readonly string[];
+    subjectFields?: readonly string[];
+    outputCheck?: OutputCheckRule;
+}
+export interface ActionGateRules {
+    job: string;
+    tools: Readonly<Record<string, ActionRule>>;
+    testRecipients?: readonly string[];
+    refuse?: readonly string[];
+    recipientFields?: readonly string[];
+    subjectFields?: readonly string[];
+    sharedDomains?: readonly string[];
+    releases?: readonly string[];
+}
+export type ActionVerdict = {
+    allow: true;
+    reason: string;
+    decision: FelsparDecision;
+} | {
+    allow: false;
+    reason: string;
+};
+export declare const emailRecipientFields: readonly ["to", "cc", "bcc", "replyTo", "reply_to"];
+export declare const emailSubjectFields: readonly ["subject"];
+export declare function gatedRule(rules: ActionGateRules, toolName: string): ActionRule | undefined;
+export interface CheckActionRequest {
+    rules: ActionGateRules;
+    toolName: string;
+    input: unknown;
+    decisions: readonly FelsparDecision[];
+    verify: ReceiptVerifier;
+    outputChecks?: readonly FelsparOutputCheck[];
+    verifyOutputCheck?: OutputCheckVerifier;
+    now?: () => number;
+}
+export declare function checkAction(request: CheckActionRequest): Promise<ActionVerdict>;
+export interface ActionGateConfig extends ActionGateRules {
+    verify: ReceiptVerifier;
+    decisionTool: string;
+    outputCheckTool?: string;
+    verifyOutputCheck?: OutputCheckVerifier;
+    decisions?: DecisionRecorder;
+    now?: () => number;
+    onVerdict?: (toolName: string, verdict: ActionVerdict) => void;
+}
+export interface ActionGate {
+    rules: ActionGateRules;
+    decisions: DecisionRecorder;
+    isGated: (toolName: string) => boolean;
+    isDecisionTool: (toolName: string) => boolean;
+    isOutputCheckTool: (toolName: string) => boolean;
+    check: (sessionId: string, toolName: string, input: unknown) => Promise<ActionVerdict>;
+}
+export declare function createActionGate(config: ActionGateConfig): ActionGate;