@felspar/sdk 0.4.0 → 0.4.2

package/README.md

@@ -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. 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.
+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).
 
@@ -66,6 +66,10 @@ if (response.status === "ready") {
 
 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 a `recovery` of `fix_input`, `retry` or `escalate`, and any `escalation` it names, such as for `attempt_limit_reached`).
@@ -167,3 +171,13 @@ Full documentation: [docs.felspar.ai](https://docs.felspar.ai).
 ## License
 
 Apache-2.0
+
+### Decision diagrams for people
+
+The hosted client's `getReleaseGraph(releaseId)`, `getProposalGraph(proposalId)`
+and `getDecisionGraph(executionObjectId)` read canonical Mermaid diagrams with
+release/material pins and a dashboard link. These inspection methods require a
+person's session and current source access; agent keys are refused. A decision
+graph reproduces the saved receipt on its original release. Check `status` before
+using `mermaid`: unavailable history is not an inferred path. Display the returned
+source unchanged.