@felspar/sdk 0.3.0 → 0.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 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 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.
+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, 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 released pack, and the SDK does not reimplement them.
 
 The modules under `draft/` may change between minor versions while the API settles, before 1.0.
 
@@ -22,7 +22,7 @@ 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.
+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 → Company 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. The tools carry the method: `get_job_requirements` says what to gather and how, and each result says what to do next, so the agent needs no Felspar skill or prompt of its own.
 
 Over MCP, `get_job_requirements` and `get_job_decision` answer compactly by default. The brief's `input` lists the arguments and a short `facts` example from the job's own questions. The decision keeps what the agent acts on, plus `executionObjectId`, the full `receipt`, the `context` capsule and `explanation.evidenceFreshUntil`, which is what the action gate records and verifies. `detail: "full"` returns the REST brief or result unchanged. The agent sends no execution ID: calling `get_job_decision` again with the same arguments within the same hour returns the decision already made, and `blocked` means that first call is still running. See [MCP tools](https://docs.felspar.ai/reference/mcp-tools).
 
@@ -36,18 +36,23 @@ const felspar = createHostedFelsparClient({
   agentKey: process.env.FELSPAR_AGENT_KEY,
 });
 
-// What the job needs: questions, evidence rules, outcomes and their outputs.
-const job = await felspar.describeJob(releaseId, "classify-prospect");
+// The jobs this agent key may run, by ID.
+const { jobs } = await felspar.listJobs();
+
+// What the job needs (questions, evidence rules, outcomes and their outputs),
+// on the release Felspar runs for this key now.
+const job = await felspar.describeCurrentJob("route-support-ticket");
+const releaseId = job.release.releaseId;
 
 // Facts in, decision out. The release pin comes from the job description.
 const response = await felspar.resolveFacts(releaseId, {
-  jobId: "classify-prospect",
+  jobId: "route-support-ticket",
   executionId: crypto.randomUUID(),
-  entityId: "acme.com",
+  entityId: "48213",
   facts: {
-    region: {
-      text: "Acme is headquartered in Lyon, France.",
-      source: { class: "crm", id: "acct-123", observedAt: new Date().toISOString() },
+    request_type: {
+      text: "I was charged twice for my March invoice.",
+      source: { class: "ticket-thread", id: "48213", observedAt: new Date().toISOString() },
     },
   },
 });
@@ -55,14 +60,19 @@ 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();
 ```
 
+`describeJob(releaseId, jobId)` describes a release you already know, such as one you pinned.
+
+Facts can come straight from a system of record, with no agent in between: send each question's evidence as the source's own words (`text`, such as a ticket's body or an account record's "Plan: Business (monthly)") with where it came from (`source.class`, `source.id`, `source.observedAt`). Felspar classifies those words for answer-choice and yes/no questions; a bare label such as `{ value: "business" }` is refused with `label_needs_mapping`, because the released question decides what the words mean. Number and date questions take a typed `{ value }` (a date as `YYYY-MM-DD`). Only the job's own question keys are accepted (`unknown_question` otherwise).
+
+Words a person gave the agent (a line from a call, a message) are evidence too: send them as given with `source: { class, manual: true, locator }`, naming in `locator` the source they came from, and no `id` or `observedAt`; Felspar stamps the time it received them, and the result and its receipt list them under `manualFacts`. A job whose description carries `manualFacts: { allowed: false }` refuses them (`manual_facts_refused`): quote the source record itself.
+
+`verifyReceipt(executionObjectId, { receipt, expectedReceiptDigest, deliveredCapsule })` asks Felspar to replay a decision and compare its receipt, and `checkOutput(job, { executionId, text, output? })` checks text written for one of your decisions (`readOutputCheck(job, checkId)` reads a check back).
+
 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`).
+A refused request throws `FelsparRequestError` with the HTTP `status` and the service's `refusal` (its `error` code, where there is one a `fix` and a `recovery` of `fix_input`, `retry` or `escalate`, and any `escalation` it names, such as for `attempt_limit_reached`).
 
 ## Action gate
 
@@ -150,16 +160,9 @@ Outside an agent framework, `checkAction({ rules, toolName, input, decisions, ve
 
 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 (its version matches the package's) 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
-```
+## Examples
 
-The directory defaults to `agent`, where an Eve agent keeps its skills; an existing copy is kept unless you pass `--force`.
+[felspar-examples](https://github.com/orchidautomation/felspar-examples) has complete projects: an Eve agent, the same agent with email drafts behind the action gate, and a script that gets a decision with no agent.
 
 ## Documentation