@felspar/sdk 0.1.1 → 0.2.1

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

@@ -1,8 +1,9 @@
 import {
+  denialText,
   entityIdOf,
   jobOf
-} from "./chunks/chunk-6EZBI7O6.js";
-import "./chunks/chunk-C2VMKF3S.js";
+} from "./chunks/chunk-Y6KRRIQI.js";
+import "./chunks/chunk-XLKRU5RA.js";
 
 // src/draft-action-gate-claude.ts
 function felsparPreToolUse(gate) {
@@ -19,7 +20,7 @@ function felsparPreToolUse(gate) {
       hookSpecificOutput: {
         hookEventName: "PreToolUse",
         permissionDecision: "deny",
-        permissionDecisionReason: `Felspar's gate: ${verdict.reason}`
+        permissionDecisionReason: `Felspar's gate: ${denialText(verdict)}`
       }
     };
   };
@@ -30,9 +31,9 @@ function felsparPostToolUse(gate) {
     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);
+    if (input.hook_event_name === "PostToolUse" && gate.isDecisionTool(input.tool_name ?? "")) {
+      const entity = entityIdOf(input.tool_input);
+      gate.decisions.record(input.session_id, { entity, job }, input.tool_response);
     }
     return {};
   };

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

@@ -1,52 +1,9 @@
 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 };
-}
+  felsparDecisionEvents,
+  felsparGate
+} from "./chunks/chunk-B4BWUYQY.js";
+import "./chunks/chunk-Y6KRRIQI.js";
+import "./chunks/chunk-XLKRU5RA.js";
 export {
   felsparDecisionEvents,
   felsparGate

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

@@ -1,8 +1,9 @@
 import {
+  denialText,
   entityIdOf,
   jobOf
-} from "./chunks/chunk-6EZBI7O6.js";
-import "./chunks/chunk-C2VMKF3S.js";
+} from "./chunks/chunk-Y6KRRIQI.js";
+import "./chunks/chunk-XLKRU5RA.js";
 
 // src/draft-action-gate-openai.ts
 function argumentsOf(text) {
@@ -30,7 +31,7 @@ function felsparToolInputGuardrail(gate, options) {
       return verdict.allow ? { behavior: { type: "allow" }, outputInfo: { reason: verdict.reason } } : {
         behavior: {
           type: "rejectContent",
-          message: `Felspar's gate denied this call: ${verdict.reason}`
+          message: `Felspar's gate denied this call: ${denialText(verdict)}`
         }
       };
     }
@@ -46,9 +47,9 @@ function felsparDecisionOutputGuardrail(gate, options) {
       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);
+      if (gate.isDecisionTool(data.toolCall.name)) {
+        const session = options.sessionOf(data.context);
+        gate.decisions.record(session, { entity: entityIdOf(input), job }, data.output);
       }
       return { behavior: { type: "allow" } };
     }

package/dist/draft-action-gate.js

@@ -3,9 +3,11 @@ import {
   createActionGate,
   createDecisionRecorder,
   decisionFromResult,
+  denialText,
   emailRecipientFields,
   emailSubjectFields,
   entityIdOf,
+  felsparJobDescriber,
   felsparOutputCheckVerifier,
   felsparVerifier,
   gatedRule,
@@ -14,16 +16,18 @@ import {
   outputCheckFromResult,
   outputTextDigest,
   sharedDomains
-} from "./chunks/chunk-6EZBI7O6.js";
-import "./chunks/chunk-C2VMKF3S.js";
+} from "./chunks/chunk-Y6KRRIQI.js";
+import "./chunks/chunk-XLKRU5RA.js";
 export {
   checkAction,
   createActionGate,
   createDecisionRecorder,
   decisionFromResult,
+  denialText,
   emailRecipientFields,
   emailSubjectFields,
   entityIdOf,
+  felsparJobDescriber,
   felsparOutputCheckVerifier,
   felsparVerifier,
   gatedRule,

package/dist/draft-hosted-client.js

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

package/dist/eve.js

@@ -0,0 +1,53 @@
+import {
+  felsparDecisionEvents,
+  felsparGate
+} from "./chunks/chunk-B4BWUYQY.js";
+import "./chunks/chunk-Y6KRRIQI.js";
+import "./chunks/chunk-XLKRU5RA.js";
+
+// src/eve.ts
+var felsparMcpUrl = "https://mcp.felspar.ai/mcp";
+var felsparTools = [
+  "list_jobs",
+  "get_job_requirements",
+  "get_job_decision",
+  "check_output"
+];
+var felsparDescription = "Felspar: the company's approved decisions. list_jobs lists the jobs this agent may run with each one's purpose; get_job_requirements says everything a job needs; get_job_decision returns the company's outcome, why, the next step, any escalation, and a receipt; check_output checks text you wrote for that decision against the company's rules.";
+function environment(name) {
+  const host = globalThis;
+  const value = host.process?.env?.[name];
+  return value === void 0 || value === "" ? void 0 : value;
+}
+var localHosts = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function endpoint(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" && !localHosts.has(parsed.hostname)) {
+    throw new Error(`Felspar's MCP URL must use HTTPS: ${parsed.origin}`);
+  }
+  return parsed.href;
+}
+function felsparConnection(options = {}) {
+  const url = endpoint(options.url ?? environment("FELSPAR_MCP_URL") ?? felsparMcpUrl);
+  return {
+    url,
+    description: options.description ?? felsparDescription,
+    auth: {
+      getToken: async () => {
+        const token = options.agentKey ?? environment("FELSPAR_AGENT_KEY");
+        if (token === void 0 || token === "") {
+          throw new Error("Set FELSPAR_AGENT_KEY in .env (Felspar web page \u2192 Workspace \u2192 Agents).");
+        }
+        return { token };
+      }
+    },
+    protocolVersionDiscovery: false,
+    tools: { allow: felsparTools }
+  };
+}
+export {
+  felsparConnection,
+  felsparDecisionEvents,
+  felsparGate,
+  felsparMcpUrl
+};

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

@@ -0,0 +1,31 @@
+export declare const emailRecipientFields: readonly ["to", "cc", "bcc", "replyTo", "reply_to"];
+export declare const emailSubjectFields: readonly ["subject"];
+type Input = Record<string, unknown>;
+export interface CaseRules {
+    testRecipients?: readonly string[];
+    recipientFields?: readonly string[];
+    subjectFields?: readonly string[];
+}
+export interface CaseRule {
+    recipientFields?: readonly string[];
+    subjectFields?: readonly string[];
+    entity?: {
+        field: string;
+    };
+}
+export interface CaseScope {
+    rules: CaseRules;
+    rule: CaseRule;
+    entities: readonly string[];
+}
+export interface Found {
+    company?: string | undefined;
+    reason?: string;
+    missing?: true;
+}
+export declare const foldCase: (text: string) => string;
+export declare const caseKeyOf: (rule: CaseRule) => (text: string) => string;
+export declare const sameField: (names: readonly string[]) => (field: string) => boolean;
+export declare function testListProblem(scope: Pick<CaseScope, "rules" | "rule">, input: Input): string | null;
+export declare function caseFor(scope: CaseScope, input: Input): Found;
+export {};

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

@@ -1,6 +1,23 @@
 import type { FelsparOutputCheck } from "./draft-action-gate-outputs.js";
+declare const identityModes: readonly ["provided", "fields", "content", "issued"];
+export type IdentityMode = (typeof identityModes)[number];
+declare const escalationTriggers: readonly ["outcome", "unresolved", "attempt_limit"];
+export type EscalationTrigger = (typeof escalationTriggers)[number];
+export interface FelsparCase {
+    id: string;
+    mode: IdentityMode;
+}
+export interface FelsparEscalation {
+    id: string;
+    trigger: EscalationTrigger;
+    why: string;
+}
 export interface FelsparDecision {
     entity: string;
+    case?: FelsparCase | undefined;
+    job?: string | undefined;
+    releaseId?: string | undefined;
+    escalation?: FelsparEscalation | undefined;
     outcome: string;
     executionObjectId: string;
     receipt: {
@@ -14,16 +31,28 @@ export interface VerifiedDecision {
     entityId: string;
     releaseId?: string;
     outcome: string | null;
+    case?: {
+        id: string;
+        mode: string;
+    } | undefined;
+    escalation?: {
+        id: string;
+        trigger: string;
+    } | undefined;
 }
 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 type DecisionRequest = string | {
+    entity?: string | undefined;
+    job?: string | undefined;
+};
+export declare function decisionFromResult(request: DecisionRequest, 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;
+    record: (sessionId: string, request: DecisionRequest, output: unknown) => FelsparDecision | null;
+    noteRequest: (callId: string, request: DecisionRequest) => void;
     noteResult: (sessionId: string, callId: string, output: unknown) => FelsparDecision | null;
     decisionsIn: (sessionId: string) => readonly FelsparDecision[];
     forget: (sessionId: string) => void;
@@ -34,3 +63,4 @@ export interface DecisionRecorderLimits {
     pendingRequests?: number;
 }
 export declare function createDecisionRecorder(limits?: DecisionRecorderLimits): DecisionRecorder;
+export {};

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

@@ -0,0 +1,81 @@
+import type { EscalationTrigger, IdentityMode } from "./draft-action-gate-decisions.js";
+interface Quoted {
+    text: string;
+}
+export interface GateJobDescription {
+    job: string;
+    release: {
+        releaseId: string;
+    };
+    subject?: {
+        type: string;
+        match: "exact" | "case-insensitive";
+    } | undefined;
+    identity?: {
+        mode: IdentityMode;
+    } | undefined;
+    outcomes: readonly {
+        id: string;
+        nextStep?: Quoted | null | undefined;
+        outputs?: readonly {
+            id: string;
+        }[] | undefined;
+        escalate?: string | undefined;
+    }[];
+    escalations?: {
+        routes: readonly {
+            id: string;
+            quote: Quoted;
+        }[];
+        unresolved: string | null;
+    } | undefined;
+    whenUnresolved?: Quoted | null | undefined;
+}
+export type JobDescriber = (releaseId: string, jobId: string) => Promise<GateJobDescription>;
+export declare function felsparJobDescriber(configuration: {
+    origin: string;
+    agentKey?: string;
+    session?: string;
+    fetcher?: typeof fetch;
+}): JobDescriber;
+export declare function writesProblem(describe: JobDescriber | undefined, decided: {
+    releaseId: string | undefined;
+    jobId: string;
+    outcome: string;
+    output: string;
+}): Promise<string | null>;
+export declare function subjectOf(describe: JobDescriber, releaseId: string, jobId: string): Promise<{
+    type: string;
+    match: "exact" | "case-insensitive";
+    mode: "provided" | "fields" | "content" | "issued";
+} | null>;
+export interface GateEscalation {
+    id: string;
+    trigger: EscalationTrigger;
+    why: string | null;
+}
+export type EscalationStep = {
+    kind: "unresolved";
+    releaseId: string | undefined;
+} | {
+    kind: "outcome";
+    releaseId: string | undefined;
+    outcome: string;
+    replayed?: {
+        id: string;
+        trigger: string;
+    } | undefined;
+    recorded?: {
+        id: string;
+        why: string;
+    } | undefined;
+} | {
+    kind: "output-check";
+};
+export declare const fixOutputCheck = "Fix what check_output flagged, check it again, then retry.";
+export interface Escalated {
+    escalate?: string;
+    escalation?: GateEscalation;
+}
+export declare function escalationFor(step: EscalationStep | undefined, describe: JobDescriber | undefined, jobId: string): Promise<Escalated>;
+export {};

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

@@ -0,0 +1,15 @@
+import type { OutputCheckRule } from "./draft-action-gate-outputs.js";
+export interface ActionRule {
+    outcomes?: readonly string[];
+    writes?: string;
+    fields: readonly string[];
+    recipientFields?: readonly string[];
+    subjectFields?: readonly string[];
+    entity?: {
+        field: string;
+    };
+    outputCheck?: OutputCheckRule;
+}
+export declare function ruleProblem(rule: ActionRule): "this tool's rule must give exactly one of outcomes or writes" | "this tool's rule has unreadable outcomes" | "this tool's rule has an unreadable writes" | "this tool's rule has an unreadable entity field" | "this tool's output check is for a different output than it writes" | null;
+export declare function fieldProblem(refuse: readonly string[], rule: ActionRule, input: Record<string, unknown>): string | null;
+export declare function checkRuleOf(rule: ActionRule): OutputCheckRule | undefined;

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

@@ -0,0 +1,33 @@
+import type { CaseRule, CaseRules } from "./draft-action-gate-cases.js";
+import type { FelsparCase, FelsparDecision } from "./draft-action-gate-decisions.js";
+import type { JobDescriber } from "./draft-action-gate-describe.js";
+export interface GateSubject {
+    type: string;
+    match: "exact" | "case-insensitive";
+    mode: FelsparCase["mode"];
+}
+export interface CaseKeying {
+    key: (id: string) => string;
+    decisionKey: (decision: FelsparDecision) => string;
+}
+export type Selected = {
+    company: string;
+    decision: FelsparDecision;
+    keying: CaseKeying;
+} | {
+    company?: undefined;
+    reason: string;
+    missing?: true;
+};
+interface SelectScope {
+    rules: CaseRules & {
+        job: string;
+        sharedDomains?: readonly string[];
+    };
+    rule: CaseRule;
+    decisions: readonly FelsparDecision[];
+    describe?: JobDescriber | undefined;
+}
+type Input = Record<string, unknown>;
+export declare function selectCase(scope: SelectScope, input: Input): Promise<Selected>;
+export {};

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

@@ -1,18 +1,17 @@
-import type { FelsparOutputCheck, OutputCheckRule, OutputCheckVerifier } from "./draft-action-gate-outputs.js";
+import type { GateEscalation, JobDescriber } from "./draft-action-gate-describe.js";
+import type { FelsparOutputCheck, OutputCheckVerifier } from "./draft-action-gate-outputs.js";
+import type { ActionRule } from "./draft-action-gate-rules.js";
 import type { DecisionRecorder, FelsparDecision, ReceiptVerifier } from "./draft-action-gate-decisions.js";
+export { emailRecipientFields, emailSubjectFields } from "./draft-action-gate-cases.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 type { DecisionRecorder, DecisionRecorderLimits, DecisionRequest, EscalationTrigger, FelsparCase, FelsparDecision, FelsparEscalation, IdentityMode, ReceiptVerifier, VerifiedDecision, } from "./draft-action-gate-decisions.js";
+export { felsparJobDescriber } from "./draft-action-gate-describe.js";
+export type { GateEscalation, GateJobDescription, JobDescriber, } from "./draft-action-gate-describe.js";
 export { isCompanyDomain, sharedDomains } from "./draft-action-gate-domains.js";
+export type { ActionRule } from "./draft-action-gate-rules.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>>;
@@ -30,9 +29,14 @@ export type ActionVerdict = {
 } | {
     allow: false;
     reason: string;
+    escalate?: string;
+    escalation?: GateEscalation;
 };
-export declare const emailRecipientFields: readonly ["to", "cc", "bcc", "replyTo", "reply_to"];
-export declare const emailSubjectFields: readonly ["subject"];
+export declare function denialText(verdict: {
+    reason: string;
+    escalate?: string;
+    escalation?: GateEscalation;
+}): string;
 export declare function gatedRule(rules: ActionGateRules, toolName: string): ActionRule | undefined;
 export interface CheckActionRequest {
     rules: ActionGateRules;
@@ -42,6 +46,7 @@ export interface CheckActionRequest {
     verify: ReceiptVerifier;
     outputChecks?: readonly FelsparOutputCheck[];
     verifyOutputCheck?: OutputCheckVerifier;
+    describe?: JobDescriber;
     now?: () => number;
 }
 export declare function checkAction(request: CheckActionRequest): Promise<ActionVerdict>;
@@ -50,6 +55,7 @@ export interface ActionGateConfig extends ActionGateRules {
     decisionTool: string;
     outputCheckTool?: string;
     verifyOutputCheck?: OutputCheckVerifier;
+    describe?: JobDescriber;
     decisions?: DecisionRecorder;
     now?: () => number;
     onVerdict?: (toolName: string, verdict: ActionVerdict) => void;