@felspar/sdk 0.1.1 → 0.2.0

package/dist/eve.js

@@ -0,0 +1,53 @@
+import {
+  felsparDecisionEvents,
+  felsparGate
+} from "./chunks/chunk-247XZ6IY.js";
+import "./chunks/chunk-IY6A2423.js";
+import "./chunks/chunk-HACK7D24.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,30 @@
+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 caseFor(scope: CaseScope, input: Input): Found;
+export {};

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

@@ -0,0 +1,43 @@
+interface Quoted {
+    text: string;
+}
+export interface GateJobDescription {
+    job: string;
+    release: {
+        releaseId: string;
+    };
+    outcomes: readonly {
+        id: string;
+        nextStep?: Quoted | null | undefined;
+        outputs?: readonly {
+            id: string;
+        }[] | 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 type EscalationStep = {
+    kind: "unresolved";
+    releaseId: string | undefined;
+} | {
+    kind: "outcome";
+    releaseId: string | undefined;
+    outcome: string;
+} | {
+    kind: "output-check";
+};
+export declare const fixOutputCheck = "Fix what check_output flagged, check it again, then retry.";
+export declare function escalationFor(step: EscalationStep | undefined, describe: JobDescriber | undefined, jobId: string): Promise<string | null>;
+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.d.ts

@@ -1,18 +1,17 @@
-import type { FelsparOutputCheck, OutputCheckRule, OutputCheckVerifier } from "./draft-action-gate-outputs.js";
+import type { 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 { felsparJobDescriber } from "./draft-action-gate-describe.js";
+export type { 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,12 @@ export type ActionVerdict = {
 } | {
     allow: false;
     reason: string;
+    escalate?: string;
 };
-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;
+}): string;
 export declare function gatedRule(rules: ActionGateRules, toolName: string): ActionRule | undefined;
 export interface CheckActionRequest {
     rules: ActionGateRules;
@@ -42,6 +44,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 +53,7 @@ export interface ActionGateConfig extends ActionGateRules {
     decisionTool: string;
     outputCheckTool?: string;
     verifyOutputCheck?: OutputCheckVerifier;
+    describe?: JobDescriber;
     decisions?: DecisionRecorder;
     now?: () => number;
     onVerdict?: (toolName: string, verdict: ActionVerdict) => void;

package/dist/types/draft-hosted-client.d.ts

@@ -1539,7 +1539,7 @@ export declare function createHostedFelsparClient(configuration: {
                         outputSurface: string;
                         entries: {
                             id: string;
-                            primitive: "gaps" | "actors" | "decision_criteria" | "source_signals" | "needs_and_requirements" | "evidence_and_proof" | "boundaries" | "output_contracts" | "routing_jobs" | "evaluations";
+                            primitive: "gaps" | "actors" | "decision_criteria" | "source_signals" | "needs_and_requirements" | "evidence_and_proof" | "boundaries" | "output_contracts" | "routing_jobs" | "evaluations" | "subjects";
                             body: string;
                             source: {
                                 sourceId: string;
@@ -1588,6 +1588,61 @@ export declare function createHostedFelsparClient(configuration: {
                             max: number;
                             withProgress: number;
                         } | undefined;
+                        subjects?: {
+                            job: string;
+                            types: {
+                                id: string;
+                                entryId: string;
+                                match: "exact" | "case-insensitive";
+                                relationships: {
+                                    name: string;
+                                    subject: string;
+                                    cardinality: "one" | "many";
+                                    required: boolean;
+                                    entryId: string;
+                                }[];
+                                identifier?: string | undefined;
+                                example?: string | undefined;
+                            }[];
+                            about: {
+                                key: string;
+                                relationship: string;
+                            }[];
+                        } | undefined;
+                        escalations?: {
+                            routes: {
+                                id: string;
+                                entryId: string;
+                            }[];
+                            outcomes: {
+                                outcome: string;
+                                escalation: string;
+                            }[];
+                            unresolved: string | null;
+                            attemptLimit: string | null;
+                        } | undefined;
+                        guide?: {
+                            purpose: string | null;
+                            useWhen: string[];
+                            notFor: string[];
+                            owner: string | null;
+                        } | undefined;
+                        caseIdentity?: {
+                            mode: "provided";
+                        } | {
+                            mode: "fields";
+                            fields: {
+                                name: string;
+                                identifier: string;
+                                example: string;
+                                match: "exact" | "case-insensitive";
+                            }[];
+                        } | {
+                            mode: "content";
+                            question: string;
+                        } | {
+                            mode: "issued";
+                        } | undefined;
                     };
                     expectedPlanDigest: string;
                     requestedSurface: string;
@@ -2517,7 +2572,7 @@ export declare function createHostedFelsparClient(configuration: {
                         outputSurface: string;
                         entries: {
                             id: string;
-                            primitive: "gaps" | "actors" | "decision_criteria" | "source_signals" | "needs_and_requirements" | "evidence_and_proof" | "boundaries" | "output_contracts" | "routing_jobs" | "evaluations";
+                            primitive: "gaps" | "actors" | "decision_criteria" | "source_signals" | "needs_and_requirements" | "evidence_and_proof" | "boundaries" | "output_contracts" | "routing_jobs" | "evaluations" | "subjects";
                             body: string;
                             source: {
                                 sourceId: string;
@@ -2566,6 +2621,61 @@ export declare function createHostedFelsparClient(configuration: {
                             max: number;
                             withProgress: number;
                         } | undefined;
+                        subjects?: {
+                            job: string;
+                            types: {
+                                id: string;
+                                entryId: string;
+                                match: "exact" | "case-insensitive";
+                                relationships: {
+                                    name: string;
+                                    subject: string;
+                                    cardinality: "one" | "many";
+                                    required: boolean;
+                                    entryId: string;
+                                }[];
+                                identifier?: string | undefined;
+                                example?: string | undefined;
+                            }[];
+                            about: {
+                                key: string;
+                                relationship: string;
+                            }[];
+                        } | undefined;
+                        escalations?: {
+                            routes: {
+                                id: string;
+                                entryId: string;
+                            }[];
+                            outcomes: {
+                                outcome: string;
+                                escalation: string;
+                            }[];
+                            unresolved: string | null;
+                            attemptLimit: string | null;
+                        } | undefined;
+                        guide?: {
+                            purpose: string | null;
+                            useWhen: string[];
+                            notFor: string[];
+                            owner: string | null;
+                        } | undefined;
+                        caseIdentity?: {
+                            mode: "provided";
+                        } | {
+                            mode: "fields";
+                            fields: {
+                                name: string;
+                                identifier: string;
+                                example: string;
+                                match: "exact" | "case-insensitive";
+                            }[];
+                        } | {
+                            mode: "content";
+                            question: string;
+                        } | {
+                            mode: "issued";
+                        } | undefined;
                     };
                     expectedPlanDigest: string;
                     requestedSurface: string;
@@ -3171,6 +3281,10 @@ export declare function createHostedFelsparClient(configuration: {
                     text: string;
                 }[];
             }[] | undefined;
+            about?: {
+                relationship: string;
+                subject: string;
+            } | undefined;
         }[];
         rules: {
             id: string;
@@ -3293,6 +3407,7 @@ export declare function createHostedFelsparClient(configuration: {
                     id: string;
                 }[] | undefined;
             }[] | undefined;
+            escalate?: string | undefined;
         }[];
         guidance: {
             gather: string;
@@ -3315,6 +3430,7 @@ export declare function createHostedFelsparClient(configuration: {
                         locator?: string | undefined;
                         sensitivity?: string | undefined;
                     };
+                    about?: string | undefined;
                 } | {
                     text: string;
                     source: {
@@ -3325,6 +3441,7 @@ export declare function createHostedFelsparClient(configuration: {
                         locator?: string | undefined;
                         sensitivity?: string | undefined;
                     };
+                    about?: string | undefined;
                 }[] | {
                     value: string | number | boolean;
                     source: {
@@ -3336,7 +3453,10 @@ export declare function createHostedFelsparClient(configuration: {
                         sensitivity?: string | undefined;
                         excerpt?: string | undefined;
                     };
+                    about?: string | undefined;
                 }>;
+                related?: Record<string, string | string[]> | undefined;
+                identity?: Record<string, string> | undefined;
             } | null;
             exampleNote: string;
         };
@@ -3350,6 +3470,145 @@ export declare function createHostedFelsparClient(configuration: {
                 maxQuestions: 64;
             };
         };
+        purpose?: {
+            text: string;
+            source: {
+                sourceId: string;
+                revision: string;
+                locator: string;
+                contentDigest: string;
+            };
+            parts: {
+                locator: string;
+                text: string;
+            }[];
+        } | undefined;
+        useWhen?: {
+            text: string;
+            source: {
+                sourceId: string;
+                revision: string;
+                locator: string;
+                contentDigest: string;
+            };
+            parts: {
+                locator: string;
+                text: string;
+            }[];
+        }[] | undefined;
+        notFor?: {
+            text: string;
+            source: {
+                sourceId: string;
+                revision: string;
+                locator: string;
+                contentDigest: string;
+            };
+            parts: {
+                locator: string;
+                text: string;
+            }[];
+        }[] | undefined;
+        owner?: {
+            text: string;
+            source: {
+                sourceId: string;
+                revision: string;
+                locator: string;
+                contentDigest: string;
+            };
+            parts: {
+                locator: string;
+                text: string;
+            }[];
+        } | undefined;
+        subject?: {
+            type: string;
+            definition: {
+                text: string;
+                source: {
+                    sourceId: string;
+                    revision: string;
+                    locator: string;
+                    contentDigest: string;
+                };
+                parts: {
+                    locator: string;
+                    text: string;
+                }[];
+            };
+            match: "exact" | "case-insensitive";
+            related: {
+                identifier: string;
+                example: string;
+                match: "exact" | "case-insensitive";
+                relationship: string;
+                meaning: {
+                    text: string;
+                    source: {
+                        sourceId: string;
+                        revision: string;
+                        locator: string;
+                        contentDigest: string;
+                    };
+                    parts: {
+                        locator: string;
+                        text: string;
+                    }[];
+                };
+                cardinality: "one" | "many";
+                required: boolean;
+                subject: string;
+                definition: {
+                    text: string;
+                    source: {
+                        sourceId: string;
+                        revision: string;
+                        locator: string;
+                        contentDigest: string;
+                    };
+                    parts: {
+                        locator: string;
+                        text: string;
+                    }[];
+                };
+            }[];
+            send: string;
+            identifier?: string | undefined;
+            example?: string | undefined;
+        } | undefined;
+        identity?: {
+            mode: "provided" | "fields" | "content" | "issued";
+            send: string;
+            fields?: {
+                identifier: string;
+                example: string;
+                match: "exact" | "case-insensitive";
+                name: string;
+            }[] | undefined;
+            question?: string | undefined;
+        } | undefined;
+        escalations?: {
+            routes: {
+                id: string;
+                quote: {
+                    text: string;
+                    source: {
+                        sourceId: string;
+                        revision: string;
+                        locator: string;
+                        contentDigest: string;
+                    };
+                    parts: {
+                        locator: string;
+                        text: string;
+                    }[];
+                };
+            }[];
+            unresolved: string | null;
+            attemptLimit: string | null;
+            rule: string;
+        } | undefined;
         whenUnresolved?: {
             text: string;
             source: {
@@ -3378,6 +3637,23 @@ export declare function createHostedFelsparClient(configuration: {
             entityId: string;
             releaseId: string;
             outcome: string | null;
+            case?: {
+                id: string;
+                mode: "provided" | "fields" | "content" | "issued";
+            } | undefined;
+            subject?: {
+                type: string;
+                related: {
+                    relationship: string;
+                    subject: string;
+                    id: string;
+                    questions: string[];
+                }[];
+            } | undefined;
+            escalation?: {
+                id: string;
+                trigger: "outcome" | "unresolved" | "attempt_limit";
+            } | undefined;
         } | undefined;
     }>;
 };

package/dist/types/eve.d.ts

@@ -0,0 +1,22 @@
+export { felsparDecisionEvents, felsparGate } from "./draft-action-gate-eve.js";
+export type { EveApprovalStatus } from "./draft-action-gate-eve.js";
+export declare const felsparMcpUrl = "https://mcp.felspar.ai/mcp";
+export interface FelsparConnectionOptions {
+    url?: string;
+    agentKey?: string;
+    description?: string;
+}
+export interface FelsparConnection {
+    url: string;
+    description: string;
+    auth: {
+        getToken: () => Promise<{
+            token: string;
+        }>;
+    };
+    protocolVersionDiscovery: false;
+    tools: {
+        allow: readonly string[];
+    };
+}
+export declare function felsparConnection(options?: FelsparConnectionOptions): FelsparConnection;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@felspar/sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Client and action gate for Felspar, the shared decision system for enterprise agents.",
   "license": "Apache-2.0",
   "homepage": "https://docs.felspar.ai",
@@ -24,6 +24,10 @@
   ],
   "type": "module",
   "exports": {
+    "./eve": {
+      "types": "./dist/types/eve.d.ts",
+      "default": "./dist/eve.js"
+    },
     "./draft/hosted-client": {
       "types": "./dist/types/draft-hosted-client.d.ts",
       "default": "./dist/draft-hosted-client.js"
@@ -46,8 +50,13 @@
     },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "felspar-sdk": "bin/felspar-sdk.mjs"
+  },
   "files": [
     "dist",
+    "bin",
+    "skills/felspar/SKILL.md",
     "README.md",
     "LICENSE"
   ],