@felspar/sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,20 +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.
-
-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 under `draft/` may change between minor versions while the API
-settles, before 1.0.
+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.
+
+The modules under `draft/` may change between minor versions while the API settles, before 1.0.
 
 ## Install
 
@@ -32,12 +22,9 @@ 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.
+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.
+
+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).
 
 ## Hosted client
 
@@ -68,18 +55,18 @@ 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 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.
+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 {
@@ -110,31 +97,16 @@ const gate = createActionGate({
 
 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.
+- `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
 
@@ -174,28 +146,20 @@ toolInputGuardrails: [felsparToolInputGuardrail(gate, { sessionOf })],
 toolOutputGuardrails: [felsparDecisionOutputGuardrail(gate, { sessionOf })],
 ```
 
-Outside an agent framework,
-`checkAction({ rules, toolName, input, decisions, verify, describe })` returns
-the same verdict.
+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.
+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.
+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
 ```
 
-The directory defaults to `agent`, where an Eve agent keeps its skills; an
-existing copy is kept unless you pass `--force`.
+The directory defaults to `agent`, where an Eve agent keeps its skills; an existing copy is kept unless you pass `--force`.
 
 ## Documentation