@felspar/sdk 0.2.0 → 0.2.1

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

@@ -2,8 +2,8 @@ import {
   denialText,
   entityIdOf,
   jobOf
-} from "./chunks/chunk-IY6A2423.js";
-import "./chunks/chunk-HACK7D24.js";
+} from "./chunks/chunk-Y6KRRIQI.js";
+import "./chunks/chunk-XLKRU5RA.js";
 
 // src/draft-action-gate-claude.ts
 function felsparPreToolUse(gate) {
@@ -31,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,9 +1,9 @@
 import {
   felsparDecisionEvents,
   felsparGate
-} from "./chunks/chunk-247XZ6IY.js";
-import "./chunks/chunk-IY6A2423.js";
-import "./chunks/chunk-HACK7D24.js";
+} 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

@@ -2,8 +2,8 @@ import {
   denialText,
   entityIdOf,
   jobOf
-} from "./chunks/chunk-IY6A2423.js";
-import "./chunks/chunk-HACK7D24.js";
+} from "./chunks/chunk-Y6KRRIQI.js";
+import "./chunks/chunk-XLKRU5RA.js";
 
 // src/draft-action-gate-openai.ts
 function argumentsOf(text) {
@@ -47,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

@@ -16,8 +16,8 @@ import {
   outputCheckFromResult,
   outputTextDigest,
   sharedDomains
-} from "./chunks/chunk-IY6A2423.js";
-import "./chunks/chunk-HACK7D24.js";
+} from "./chunks/chunk-Y6KRRIQI.js";
+import "./chunks/chunk-XLKRU5RA.js";
 export {
   checkAction,
   createActionGate,

package/dist/draft-hosted-client.js

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

package/dist/eve.js

@@ -1,9 +1,9 @@
 import {
   felsparDecisionEvents,
   felsparGate
-} from "./chunks/chunk-247XZ6IY.js";
-import "./chunks/chunk-IY6A2423.js";
-import "./chunks/chunk-HACK7D24.js";
+} 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";

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

@@ -26,5 +26,6 @@ export interface Found {
 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

@@ -1,3 +1,4 @@
+import type { EscalationTrigger, IdentityMode } from "./draft-action-gate-decisions.js";
 interface Quoted {
     text: string;
 }
@@ -6,13 +7,28 @@ export interface GateJobDescription {
     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>;
@@ -28,6 +44,16 @@ export declare function writesProblem(describe: JobDescriber | undefined, decide
     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;
@@ -35,9 +61,21 @@ export type EscalationStep = {
     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 declare function escalationFor(step: EscalationStep | undefined, describe: JobDescriber | undefined, jobId: string): Promise<string | null>;
+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-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,12 +1,12 @@
-import type { JobDescriber } from "./draft-action-gate-describe.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 { GateJobDescription, JobDescriber } 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";
@@ -30,10 +30,12 @@ export type ActionVerdict = {
     allow: false;
     reason: string;
     escalate?: string;
+    escalation?: GateEscalation;
 };
 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 {

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

@@ -1,9 +1,143 @@
 import { z } from "zod";
+declare const FelsparCaseSchema: z.ZodObject<{
+    id: z.ZodString;
+    mode: z.ZodEnum<{
+        provided: "provided";
+        fields: "fields";
+        content: "content";
+        issued: "issued";
+    }>;
+}, z.core.$strip>;
+declare const FelsparRelatedSchema: z.ZodObject<{
+    relationship: z.ZodString;
+    subject: z.ZodString;
+    id: z.ZodString;
+    questions: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const FelsparResultSubjectSchema: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+    related: z.ZodArray<z.ZodObject<{
+        relationship: z.ZodString;
+        subject: z.ZodString;
+        id: z.ZodString;
+        questions: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const FelsparEscalationSchema: z.ZodObject<{
+    id: z.ZodString;
+    trigger: z.ZodEnum<{
+        outcome: "outcome";
+        unresolved: "unresolved";
+        attempt_limit: "attempt_limit";
+    }>;
+    why: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+declare const FelsparJobResultSchema: z.ZodObject<{
+    status: z.ZodString;
+    reason: z.ZodNullable<z.ZodString>;
+    result: z.ZodNullable<z.ZodObject<{
+        executionId: z.ZodString;
+        releaseId: z.ZodString;
+        releaseDigest: z.ZodString;
+        outcome: z.ZodNullable<z.ZodString>;
+        scoring: z.ZodUnknown;
+        context: z.ZodUnknown;
+        receipt: z.ZodUnknown;
+        case: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            mode: z.ZodEnum<{
+                provided: "provided";
+                fields: "fields";
+                content: "content";
+                issued: "issued";
+            }>;
+        }, z.core.$strip>>;
+        subject: z.ZodOptional<z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+            related: z.ZodArray<z.ZodObject<{
+                relationship: z.ZodString;
+                subject: z.ZodString;
+                id: z.ZodString;
+                questions: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        escalation: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            trigger: z.ZodEnum<{
+                outcome: "outcome";
+                unresolved: "unresolved";
+                attempt_limit: "attempt_limit";
+            }>;
+            why: z.ZodObject<{
+                text: z.ZodString;
+            }, z.core.$loose>;
+        }, z.core.$strip>>;
+        missing: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export type FelsparJobResult = z.infer<typeof FelsparJobResultSchema>;
+export type FelsparJobCase = z.infer<typeof FelsparCaseSchema>;
+export type FelsparRelatedRecord = z.infer<typeof FelsparRelatedSchema>;
+export type FelsparResultSubject = z.infer<typeof FelsparResultSubjectSchema>;
+export type FelsparJobEscalation = z.infer<typeof FelsparEscalationSchema>;
+interface QuotedWords {
+    text: string;
+}
+export interface FelsparJobSubject {
+    type: string;
+    definition: QuotedWords;
+    identifier?: string | undefined;
+    example?: string | undefined;
+    match: "exact" | "case-insensitive";
+    related: readonly {
+        relationship: string;
+        meaning: QuotedWords;
+        cardinality: "one" | "many";
+        required: boolean;
+        subject: string;
+        definition: QuotedWords;
+        identifier: string;
+        example: string;
+        match: "exact" | "case-insensitive";
+    }[];
+    send: string;
+}
+export interface FelsparJobIdentity {
+    mode: FelsparJobCase["mode"];
+    send: string;
+    fields?: readonly {
+        name: string;
+        identifier: string;
+        example: string;
+        match: string;
+    }[];
+    question?: string | undefined;
+}
+export interface FelsparFactsRequest {
+    jobId: string;
+    executionId: string;
+    expectedReleaseDigest?: string;
+    entityId?: string;
+    identity?: Record<string, string>;
+    related?: Record<string, string | string[]>;
+    facts: Record<string, unknown>;
+}
+declare const FelsparJobListSchema: z.ZodObject<{
+    jobs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type FelsparJobList = z.infer<typeof FelsparJobListSchema>;
 declare const refusalSchema: z.ZodPipe<z.ZodObject<{
     error: z.ZodString;
     path: z.ZodOptional<z.ZodArray<z.ZodString>>;
     currentReleaseDigest: z.ZodOptional<z.ZodString>;
     retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+    escalation: z.ZodOptional<z.ZodUnknown>;
     issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         path: z.ZodArray<z.ZodString>;
@@ -14,6 +148,13 @@ declare const refusalSchema: z.ZodPipe<z.ZodObject<{
         path: string[];
     }[] | undefined;
     fix?: string;
+    escalation?: {
+        id: string;
+        trigger: "outcome" | "unresolved" | "attempt_limit";
+        why: {
+            text: string;
+        };
+    };
     error: string;
     path?: string[] | undefined;
     currentReleaseDigest?: string | undefined;
@@ -23,6 +164,7 @@ declare const refusalSchema: z.ZodPipe<z.ZodObject<{
     path?: string[] | undefined;
     currentReleaseDigest?: string | undefined;
     retryAfterSeconds?: number | undefined;
+    escalation?: unknown;
     issues?: {
         code: string;
         path: string[];
@@ -43,35 +185,14 @@ export declare function createHostedFelsparClient(configuration: {
     agentKey?: string;
     fetcher?: typeof fetch;
 }): {
-    executeJob: (id: string, value: unknown) => Promise<{
-        status: string;
-        reason: string | null;
-        result: {
-            [x: string]: unknown;
-            executionId: string;
-            releaseId: string;
-            releaseDigest: string;
-            outcome: string | null;
-            scoring: unknown;
-            context: unknown;
-            receipt: unknown;
-        } | null;
-    }>;
-    resolveFacts: (id: string, value: Record<string, unknown>) => Promise<{
-        status: string;
-        reason: string | null;
-        result: {
-            [x: string]: unknown;
-            executionId: string;
-            releaseId: string;
-            releaseDigest: string;
-            outcome: string | null;
-            scoring: unknown;
-            context: unknown;
-            receipt: unknown;
-        } | null;
+    resolveFacts: (id: string, value: FelsparFactsRequest | Record<string, unknown>) => Promise<FelsparJobResult>;
+    listJobs: () => Promise<{
+        jobs: {
+            id: string;
+        }[];
     }>;
-    resolveJob: (id: string, value: unknown) => Promise<{
+    resolveJob: (id: string, value: unknown) => Promise<FelsparJobResult>;
+    executeJob: (id: string, value: unknown) => Promise<{
         status: string;
         reason: string | null;
         result: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@felspar/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Client and action gate for Felspar, the shared decision system for enterprise agents.",
   "license": "Apache-2.0",
   "homepage": "https://docs.felspar.ai",

package/skills/felspar/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: felspar
-description: Use this skill when a task involves a Felspar job or a company decision about a case, such as evaluating, classifying or qualifying a company, routing or answering a support ticket, or deciding any other record by the company's approved rules. Load it when choosing which Felspar job fits a task; before gathering evidence or calling list_jobs, get_job_requirements, get_job_decision or check_output; before writing a reply or any other text for a decided case; before an action that follows a decision, such as a draft or a record update; and whenever a Felspar result comes back held, undecided, refused or with an escalation, or Felspar's action gate denies a call.
+description: Use this skill when a task involves a Felspar job or a company decision about a case, such as evaluating, classifying or qualifying a company, routing or answering a support ticket, or deciding any other record by the company's approved rules. Load it when choosing which Felspar job fits a task; before gathering evidence or calling list_jobs, get_job_requirements, get_job_decision or check_output; before writing a reply or any other text for a decided case; before an action that follows a decision, such as a draft or a record update; and whenever a Felspar result comes back held, undecided, refused or with an escalation or a case ID to reuse, or Felspar's action gate denies a call or names an escalation.
 metadata:
-  version: "0.2.0"
+  version: "0.2.1"
 ---
 
 # Working with Felspar
@@ -94,9 +94,10 @@ Show each output above the answer block: the final text, then one line with its
 Actions that follow a decision (an email draft, a ticket reply, a CRM update) may pass Felspar's action gate before they run. The gate checks, in code, that Felspar decided on the case the action is about, that the decided outcome allows the action (or lists the output it writes), that the receipt still verifies and, where required, that Felspar passed exactly the text being sent. So:
 
 - Act only on a decided outcome, and only as its next step says. A held or undecided case gets no action.
-- Name the case the way the tool expects. An email about a company goes to people at the company Felspar decided on, one company per email. An action on a record carries the record's ID exactly as you sent it as `entity_id`.
+- Name the case the way the tool expects. An email about a company goes to people at the company Felspar decided on, one company per email. An action on a record carries the case's ID: `result.case.id` exactly when the result names a case (always for an issued, fields or content job), otherwise the record's ID exactly as you sent it as `entity_id`. Never put another case's ID on an action.
+- Work one case at a time: when the tool has no field for the case ID, the gate binds the action to the one case you decided in this conversation.
 - Send exactly the text `check_output` passed, and set only the fields the tool needs; the gate denies anything else.
-- If the gate denies an action, don't retry or rephrase it to get around the gate. Report the reason. When the denial gives a `Next step:` (the company's own, quoted from the policy), do that instead; when it asks you to fix what `check_output` flagged, fix the text, check it again and only then retry; otherwise escalate.
+- If the gate denies an action, don't retry or rephrase it to get around the gate. Report the reason. When the denial gives a `Next step:` (the company's own, quoted from the policy), do that instead; when it names an `Escalation <id>`, report that id exactly with its why and hand the case off; when it asks you to fix what `check_output` flagged, fix the text, check it again and only then retry; otherwise escalate.
 
 ## 5. Answer