@felspar/sdk 0.1.1 → 0.2.0

package/README.md

@@ -5,14 +5,16 @@ 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 +22,23 @@ 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 `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 +49,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.
@@ -56,38 +75,75 @@ service's `refusal` (its `error` code and, where there is one, a `fix`).
 
 ## 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.)
+- `entity` says which case a call is about. By default, every recipient's
+  email domain must belong to the one company Felspar decided on. With
+  `{ field }`, that input field must hold the decision's `entity_id` (such as a
+  ticket ID), trimmed and otherwise exact, case included, as Felspar keys
+  cases (`HC-1201` and `hc-1201` are two cases). Only email domains match
+  without case.
+  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? }`. `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. It is absent when the description
+doesn't say. Every adapter below shows it 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 +174,28 @@ 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 the gate checks
-fields, recipients and the decision, not what the tool writes.
+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
+```
+
+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-247XZ6IY.js

@@ -0,0 +1,54 @@
+import {
+  denialText,
+  entityIdOf,
+  jobOf
+} from "./chunk-IY6A2423.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 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 {
+  felsparGate,
+  felsparDecisionEvents
+};