@felspar/sdk 0.1.1 → 0.2.1

package/README.md

@@ -1,18 +1,10 @@
 # @felspar/sdk
 
-Felspar is a shared, versioned decision system for enterprise agents. A
-company's approved meaning, the evidence a decision needs and the decision
-itself travel together in a released Decision Pack. Agents ask Felspar for a
-decision, get a receipt they can verify, and act only on what Felspar decided.
+Felspar is a shared, versioned decision system for enterprise agents. A company's approved meaning, the evidence a decision needs and the decision itself travel together in a released Decision Pack. Agents ask Felspar for a decision, get a receipt they can verify, and act only on what Felspar decided.
 
-This package is the TypeScript client for the hosted Felspar API and an action
-gate that keeps an agent's tools from acting without a verified Felspar
-decision. It runs on Node.js 24 or later, and its only dependency is `zod`.
-The SDK is a transport client: decisions and policy stay with the Felspar
-service, and the SDK does not reimplement them.
+This package connects an agent to Felspar: an [Eve](https://github.com/vercel/eve) connection in two lines, a TypeScript client for the hosted Felspar API, an action gate that keeps an agent's tools from acting without a verified Felspar decision, and the agent skill for running any Felspar job. It runs on Node.js 24 or later, and its only dependency is `zod`. The SDK is a transport client: decisions and policy stay with the Felspar service and the released pack, and the SDK does not reimplement them.
 
-The modules live under `draft/` while the API settles: they may change between
-minor versions before 1.0.
+The modules under `draft/` may change between minor versions while the API settles, before 1.0.
 
 ## Install
 
@@ -20,6 +12,18 @@ minor versions before 1.0.
 npm install @felspar/sdk
 ```
 
+## Connect an Eve agent
+
+In `agent/connections/felspar.ts`:
+
+```ts
+import { defineMcpClientConnection } from "eve/connections";
+import { felsparConnection } from "@felspar/sdk/eve";
+export default defineMcpClientConnection(felsparConnection());
+```
+
+The agent gets Felspar's `list_jobs`, `get_job_requirements`, `get_job_decision` and `check_output` tools and nothing else. The key is the agent's own, created on the Felspar web page (Workspace → Agents) and read from `FELSPAR_AGENT_KEY` when Eve connects; the endpoint is `FELSPAR_MCP_URL`, or production. Pass `{ url, agentKey, description }` to override them. Add the skill (below) so the agent knows the method.
+
 ## Hosted client
 
 ```ts
@@ -30,7 +34,7 @@ const felspar = createHostedFelsparClient({
   agentKey: process.env.FELSPAR_AGENT_KEY,
 });
 
-// What the job needs: questions, evidence rules and outcomes.
+// What the job needs: questions, evidence rules, outcomes and their outputs.
 const job = await felspar.describeJob(releaseId, "classify-prospect");
 
 // Facts in, decision out. The release pin comes from the job description.
@@ -49,45 +53,67 @@ const response = await felspar.resolveFacts(releaseId, {
 if (response.status === "ready") {
   console.log(response.result?.outcome, response.result?.receipt);
 }
+
+// The jobs this agent key may run, by ID.
+const { jobs } = await felspar.listJobs();
 ```
 
-A refused request throws `FelsparRequestError` with the HTTP `status` and the
-service's `refusal` (its `error` code and, where there is one, a `fix`).
+How a case is identified comes from the job's description (`identity`): send `entityId` for the record's own ID (`provided`), `identity` field values (`fields`), or nothing (`content`, and the first decision of an `issued` job). The result's `case` gives the case's `id` and `mode`; send `case.id` as `entityId` for every later decision on the same case. Results are typed (`FelsparJobResult`): `case`, `subject` with its `related` records, `escalation` (`id`, `trigger`, `why`) and `missing` for a gap.
+
+A refused request throws `FelsparRequestError` with the HTTP `status` and the service's `refusal` (its `error` code, where there is one a `fix`, and any `escalation` it names, such as for `attempt_limit_reached`).
 
 ## Action gate
 
-The gate sits in front of a tool that acts, such as writing an email draft. It
-allows a call only when the call's fields are allowed, every recipient belongs
-to a company Felspar decided on in this session, Felspar re-verifies that
-decision's receipt, and the decided outcome allows the tool. Any error denies.
+The gate sits in front of a tool that acts, such as writing an email draft or replying to a ticket. It allows a call only when the call's fields are allowed, the call is about a case Felspar decided on in this session, Felspar re-verifies that decision's receipt, and the decided outcome permits the tool. Any error, and anything unknown or ambiguous, denies.
 
 ```ts
-import { createActionGate, felsparVerifier } from "@felspar/sdk/draft/action-gate";
+import {
+  createActionGate,
+  felsparJobDescriber,
+  felsparOutputCheckVerifier,
+  felsparVerifier,
+} from "@felspar/sdk/draft/action-gate";
 
+const felspar = { origin: "https://api.felspar.ai", agentKey };
 const gate = createActionGate({
-  job: "classify-prospect",
-  decisionTool: "felspar__get_job_decision", // exact tool name in your runtime
+  job: "route-support-ticket",
+  decisionTool: "felspar__get_job_decision", // exact tool names in your runtime
+  outputCheckTool: "felspar__check_output",
   tools: {
-    agentmail__create_draft: {
-      outcomes: ["platform-builder"],
-      fields: ["inboxId", "to", "cc", "bcc", "replyTo", "subject", "text", "html", "labels"],
+    helpdesk__reply: {
+      writes: "billing-team-reply",
+      entity: { field: "ticketId" },
+      fields: ["ticketId", "body"],
+      outputCheck: { fields: ["body"] },
     },
   },
-  verify: felsparVerifier({ origin: "https://api.felspar.ai", agentKey }),
+  verify: felsparVerifier(felspar),
+  describe: felsparJobDescriber(felspar),
+  verifyOutputCheck: felsparOutputCheckVerifier(felspar),
 });
 ```
 
-Then connect it to your agent framework. Tool names must match exactly as the
-runtime reports them.
+What a tool may do comes from the released pack, not from the gate's config:
+
+- `writes` names the output the tool writes, by its id in the pack. The call is allowed only when the released job description lists that output under the outcome Felspar's replay reports. (A rule may give `outcomes`, a list of outcome ids, instead; exactly one of the two.)
+- Which case a call is about comes from the released job's subject and identity. A decision is recorded by the `case.id` Felspar's result names (so an agent that sends no `entity_id`, for an issued, fields or content job, still gets one), and Felspar's replay must name the same case ID and mode. By default:
+  - for a job whose subject is a provided, case-insensitive ID such as a web domain (or a release with no subject), every recipient's email domain must belong to the one company Felspar decided on; a decided ID that isn't a company domain allows no recipient, so give such a rule an entity field;
+  - for any other job, the call is about the one case decided in the session for this job; with several, the call is denied until the rule names a field.
+- `entity: { field }` overrides that: the input field must hold the case's ID, the record's own ID (such as a ticket ID) or the `case.id` Felspar issued or derived, trimmed and matched by the subject's match rule (exact unless the subject is case-insensitive; with no subject, `HC-1201` and `hc-1201` are two cases). Recipients are then not tied to the case, so a tool that can address anyone should also limit them (`testRecipients`, or the tool's own settings).
+- `outputCheck` requires that Felspar passed exactly the text the call sends for that decision (`check_output`); with `writes`, for that output.
+
+A denial is `{ allow: false, reason, escalate?, escalation? }`. `escalate` is the company's next step, quoted from the released description: the outcome's next step when the outcome doesn't permit the tool, or what to do when nothing is decided. For a missing or failed output check it is the fixed instruction to fix what `check_output` flagged and check again. `escalation` is the hand-off the policy names: `{ id, trigger, why }`, with the id from Felspar's replay of the outcome (or the job's unresolved path) and `why` quoted from the release. Both are absent when the release doesn't say. Every adapter below shows them to the model with the reason.
+
+Then connect the gate to your agent framework. Tool names must match exactly as the runtime reports them.
 
 ### Eve
 
 ```ts
-import { felsparDecisionEvents, felsparGate } from "@felspar/sdk/draft/action-gate/eve";
+import { felsparDecisionEvents, felsparGate } from "@felspar/sdk/eve";
 
 // On the connection whose tools act:
 approval: felsparGate(gate),
-// And in a hook that records Felspar's decisions:
+// And in a hook that records Felspar's decisions and output checks:
 export default defineHook({ events: felsparDecisionEvents(gate) });
 ```
 
@@ -118,12 +144,20 @@ toolInputGuardrails: [felsparToolInputGuardrail(gate, { sessionOf })],
 toolOutputGuardrails: [felsparDecisionOutputGuardrail(gate, { sessionOf })],
 ```
 
-Outside an agent framework, `checkAction({ rules, toolName, input, decisions, verify })`
-returns `{ allow, reason }`.
+Outside an agent framework, `checkAction({ rules, toolName, input, decisions, verify, describe })` returns the same verdict.
+
+A Felspar receipt records what Felspar decided from the evidence it was given. It is not a factual, legal or security certification, and a passed output check means the text follows the released rules, not that it is true or approved to send.
+
+## Agent skill
+
+The package ships the skill that teaches an agent the method for any Felspar job: get the requirements, gather exact evidence, get the decision, write and check what the decision asks for, and escalate with the company's next step.
+
+```bash
+npx @felspar/sdk skill        # writes agent/skills/felspar/SKILL.md
+npx @felspar/sdk skill .claude --force
+```
 
-A Felspar receipt records what Felspar decided from the evidence it was given.
-It is not a factual, legal or security certification, and the gate checks
-fields, recipients and the decision, not what the tool writes.
+The directory defaults to `agent`, where an Eve agent keeps its skills; an existing copy is kept unless you pass `--force`.
 
 ## Documentation
 

package/bin/felspar-sdk.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// The package's command line: `npx @felspar/sdk skill [dir] [--force]`.
+import { main } from "./skill.mjs";
+
+try {
+  console.log(`Wrote ${main(process.argv.slice(2))}`);
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/bin/skill.mjs

@@ -0,0 +1,33 @@
+// `npx @felspar/sdk skill [dir] [--force]` copies Felspar's agent skill, the
+// method for running any Felspar job, to <dir>/skills/felspar/SKILL.md. The
+// directory defaults to agent, where an Eve agent keeps its skills.
+import { constants, copyFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+
+export const skillSource = path.join(import.meta.dirname, "../skills/felspar/SKILL.md");
+const usage = "usage: npx @felspar/sdk skill [dir] [--force]";
+
+// Copies the skill and returns where it went. Without force an existing file
+// is kept: COPYFILE_EXCL fails on any existing path, a dangling link included.
+export function installSkill(directory = "agent", { force = false } = {}) {
+  const target = path.join(directory, "skills", "felspar", "SKILL.md");
+  const mode = force ? 0 : constants.COPYFILE_EXCL;
+  mkdirSync(path.dirname(target), { recursive: true });
+  try {
+    copyFileSync(skillSource, target, mode);
+  } catch (error) {
+    throw error.code === "EEXIST"
+      ? new Error(`${target} exists; pass --force to replace it`, { cause: error })
+      : error;
+  }
+  return target;
+}
+
+export function main(argv) {
+  const force = argv.includes("--force");
+  const [command, directory, ...rest] = argv.filter((argument) => argument !== "--force");
+  if (command !== "skill" || rest.length > 0 || directory?.startsWith("-")) {
+    throw new Error(usage);
+  }
+  return installSkill(directory, { force });
+}

package/dist/chunks/chunk-B4BWUYQY.js

@@ -0,0 +1,53 @@
+import {
+  denialText,
+  entityIdOf,
+  jobOf
+} from "./chunk-Y6KRRIQI.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 verdict.allow ? { type: "approved", reason: verdict.reason } : { type: "denied", reason: denialText(verdict) };
+  };
+}
+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 job = jobOf(action.input);
+      if (gate.isDecisionTool(action.toolName ?? "")) {
+        gate.decisions.noteRequest(action.callId, { entity: entityIdOf(action.input), job });
+      }
+      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 {
+  felsparGate,
+  felsparDecisionEvents
+};