@visiq/harness 0.2.20 → 0.2.21

package/README.md

@@ -62,6 +62,120 @@ variables (option takes precedence, then the env var):
 | `endpoint` | `VISIQ_ENDPOINT` | Backend endpoint URL. Optional — defaults to the managed SaaS host `https://api.visiqlabs.com`; set it explicitly only for onprem / self-hosted deployments. |
 | `agentId` | `VISIQ_AGENT_ID` | Stable agent identity. If unset it is derived (package name → hostname) and auto-provisioned in monitor mode. |
 | `hitlTimeoutMs` | `VISIQ_HITL_TIMEOUT_MS` | Max wait (ms) for a human to resolve an `approval_required` decision before failing closed. Default `120000`. |
+| `timeoutMs` | `VISIQ_TIMEOUT_MS` | Per-evaluate network timeout before the action pre-gate fails **closed** on a stuck backend. Default 5s. Raise it for high-latency paths. |
+| `onInstrumentFailure` | `VISIQ_ON_INSTRUMENT_FAILURE` | `'warn'` \| `'throw'` — what to do when a framework is detected but ZERO tools are instrumented. Unset is context-sensitive: an agent that ADVERTISES tools but instruments none fails **closed**; a genuinely tool-less agent only warns. |
+| `failMode` | `VISIQ_FAIL_MODE` | `'open'` (default) \| `'closed'` — posture for **VisIQ's own** failures. Policy outcomes are unaffected. |
+| `sessionId` | *(none — deliberately)* | Explicit session key for sequence-aware rules (`input.session.*`). See [Sessions](#sessions-and-sequence-aware-rules). |
+| `identity` | *(none — deliberately)* | Per-call identity attestation for identity-binding rules. See [Identity](#identity-attestation). |
+
+Two options have **no environment variable, on purpose**. `sessionId` and
+`identity` are per-conversation and per-call facts; a process-wide env var would
+apply one value to every request an agent-per-request server handles — fusing
+unrelated users into one session, or attesting one user's principal for
+everybody. Both are strictly worse than leaving them unset.
+
+## Sessions and sequence-aware rules
+
+A rule can condition on what the session has already done
+(`input.session.event_count`, `input.session.action_counts.*`,
+`input.session.retrieved_data_categories`, …). That needs a **session key**, and
+the key comes from your application.
+
+Resolution order, highest first:
+
+1. `sessionId` passed to `visiq(target, { sessionId })`
+2. LangChain/LangGraph only: `configurable.thread_id` on the call config
+3. LangChain/LangGraph only: `configurable.session_id`
+4. a fresh id per top-level run (so a caller who threads nothing is unaffected)
+
+```ts
+// LangGraph / LangChain — nothing to configure: thread your conversation id and
+// the two turns share a session.
+await graph.invoke(input, { configurable: { thread_id: conversationId } });
+
+// Every other framework — name the conversation on the wrap.
+const agent = visiq(new Agent({ model, tools }), { sessionId: conversationId });
+```
+
+### Reach, per framework
+
+<!-- BEGIN GENERATED session-reach-table (src/session-reach.ts) -->
+| framework | native conversation key | `sessionId` option | spans runs | concurrent runs isolated |
+|---|---|---|---|---|
+| `langchain` | yes | yes | yes | yes |
+| `vercel_ai` | no | yes | yes | yes |
+| `mastra` | no | yes | yes | yes |
+| `voltagent` | no | yes | yes | yes |
+| `llamaindex` | no | yes | yes | yes |
+| `openai_agents` | no | yes | yes | no |
+| `semantic_kernel` | no | yes | yes | no |
+| `bare_tool` | no | yes | yes | no |
+<!-- END GENERATED session-reach-table -->
+
+- **native conversation key** — the harness reads a durable id from the
+  framework's own config, so you configure nothing.
+- **concurrent runs isolated** — two simultaneous runs of ONE wrapped object in
+  one process do not share a key. Where this is `no`, the framework exposes no
+  per-run context the harness can hang a scope on. For `semantic_kernel` and
+  `bare_tool`, a host key you supply is by definition shared by everything that
+  uses it — pass a *per-conversation* value, not a process-wide one.
+
+### ⚠️ Sessions accumulate IN-PROCESS
+
+The trajectory is folded into an in-memory map on the harness's own runtime:
+**512 live sessions (LRU), 30-minute idle expiry**, per process. Two turns that
+land on two replicas therefore see two **fresh, empty** sessions, and a
+sequence-aware rule can be correct, deployed and silently inert. If you run more
+than one replica, pin conversation affinity at your load balancer, or accept that
+`input.session.*` conditions only see the turns one replica handled.
+
+## Identity attestation
+
+Some rules bind a privileged action to a principal the session has **proven**:
+
+```rego
+deny if not input.normalized.write.subject_id
+         in input.session.identity.attested_subjects
+```
+
+Supply the principal per call:
+
+```ts
+const agent = visiq(new Agent({ model, tools }), {
+  sessionId: conversationId,
+  identity: () => {
+    const req = requestContext.getStore();     // YOUR request-scoped context
+    return req && { attested: [req.userId], subjectId: req.targetUserId };
+  },
+});
+```
+
+| field | meaning |
+|---|---|
+| `attested` | principals your application can PROVE for this call — an IdP/session assertion, your request context, a verification tool's result. The only field that writes `attested_subjects`. |
+| `claimed` | principals the **conversation** merely asserted. Grants nothing; exists so a rule can see the divergence. |
+| `subjectId` | the human this action acts UPON. Becomes `normalized.write.subject_id`. |
+
+**⚠️ VisIQ cannot verify this.** The harness runs inside your process, so
+`attested` is an assertion by your application — recorded, folded and
+rule-matchable, never independently checked. Source it from a channel the
+untrusted party cannot author. **A principal the model read out of the
+conversation belongs in `claimed`; if you cannot tell the two apart, pass
+neither.**
+
+Two behaviours worth knowing:
+
+- The fold runs **after** the decision, so a principal attested on turn *N* is
+  visible from turn *N+1*. That is the intended pattern: a verification step
+  registers the principal, then the privileged action binds against it.
+- With **no** `identity` supplied, a rule of the shape above does not fire at
+  all — its left operand is absent, so the condition is undefined and a
+  lower-priority rule decides. It is not a safe default; it is a no-op. Supply
+  `subjectId` to arm the rule.
+
+Values are bounded to the control plane's own limits (≤32 principals of ≤255
+characters). Oversized input is truncated rather than rejected — a rejected
+event would fail the whole evaluation, which by default proceeds *ungoverned*.
 
 ## Multi-agent delegation
 

package/dist/index.d.ts

@@ -14,6 +14,118 @@ export declare const DEFAULT_FAIL_MODE: FailMode;
  * must degrade to the DEFAULT, never invent strictness.
  */
 export declare function normalizeFailMode(raw: unknown): FailMode | undefined;
+/**
+ * IDENTITY ATTESTATION — the first-party seam an application uses to tell VisIQ
+ * *who* a governed call is being made for.
+ *
+ * ── WHY THIS FILE EXISTS ────────────────────────────────────────────────────
+ * The control plane teaches rule authors an identity-binding rule of the shape
+ *
+ *     deny if not input.normalized.write.subject_id
+ *              in input.session.identity.attested_subjects
+ *
+ * and `@visiq/runtime` has accepted `event.identity` since the fold shipped
+ * (`unified-runtime.ts` — `attested_subjects` / `claimed_subjects` /
+ * `acted_subjects`). But until this module landed, **this SDK never produced
+ * `event.identity` on any path**: there was not one `identity:` producer site in
+ * `packages/visiq-sdk-ts/src/`. This is the producer.
+ *
+ * ⚠️ AND THE DIRECTION OF THAT GAP IS THE OPPOSITE OF THE OBVIOUS READING.
+ * "`attested_subjects` is empty, so the rule denies everything" is wrong.
+ * MEASURED against the committed wasm (`identity-attestation.cell.test.ts`):
+ *
+ *   what the harness sent                         taught binding rule
+ *   ────────────────────────────────────────────  ───────────────────
+ *   nothing (every @visiq/harness deployment)     PERMIT  ← silent no-op
+ *   `normalized.write.subject_id`, attested []    DENY    ← fail-closed
+ *   `identity.attested` but NO `subjectId`        PERMIT  ← silent no-op
+ *
+ * The rule's LEFT operand is `input.normalized.write.subject_id`. Absent, the
+ * `in` relation is undefined, the rule body fails, the deny arm never fires, and
+ * a lower-priority catch-all decides. So the pre-seam behaviour was a SILENT
+ * FAIL-OPEN on the identity-binding rule class, not a safe deny — and it is the
+ * SUBJECT, not the attested set, that arms the rule. That is why
+ * {@link identityNormalized} materializes `normalized.write.subject_id` from
+ * `subjectId` rather than only forwarding `identity`.
+ *
+ * ── THE TRUST BOUNDARY, AND WHAT THE PLATFORM CAN AND CANNOT DO ─────────────
+ * **VisIQ CANNOT VERIFY WHAT YOU PASS HERE.** The harness runs inside your
+ * process; there is no channel by which the control plane could re-derive an
+ * IdP assertion from an in-process call. `attested` is therefore an ASSERTION BY
+ * YOUR APPLICATION, recorded and folded as such. What the platform guarantees is
+ * narrow and worth stating exactly:
+ *
+ *   • it is the ONLY thing that writes `input.session.identity.attested_subjects`;
+ *   • it is a grow-only set, so the fold stays commutative;
+ *   • a principal that reaches `claimed` NEVER reaches `attested`, so a rule can
+ *     SEE the divergence between "who the model says this is" and "who the
+ *     application proved".
+ *
+ * So the security property is YOURS to uphold, and it is a single rule:
+ *
+ *   **`attested` must come from a channel the untrusted party cannot author** —
+ *   an IdP/session assertion, your own request context, or the RESULT of a
+ *   verification tool. **NEVER a principal the model merely read out of the
+ *   conversation.** Anything model-derived belongs in `claimed`, which grants
+ *   nothing. A caller that cannot tell the two apart must pass NEITHER; passing
+ *   a conversational claim as `attested` silently reintroduces exactly the
+ *   forgery the binding exists to stop.
+ *
+ * ── BOUNDS (G003), AND WHY THEY ARE HERE AND NOT ONLY AT THE GATE ───────────
+ * `UnifiedRuntime` Zod-validates identity to `≤32` entries of `1..255` chars
+ * (`unified-runtime.ts` `evaluateEventSchema`). A violation THROWS out of
+ * `evaluate()`, which the harness treats as a HARNESS failure routed by
+ * `failMode` — i.e. fail-OPEN by default. So an application that handed us a
+ * 300-character subject id would make EVERY governed call in that process run
+ * UNGOVERNED, with only a warning. Normalizing here converts that into a
+ * silently-bounded value, exactly as `resolveLangchainSessionId` bounds the
+ * session key for the same reason.
+ *
+ * Truncation direction is deliberate: dropping entries from `attested` can only
+ * SHRINK the proven set, so a binding rule denies MORE, never less.
+ */
+/**
+ * An identity attestation for one governed call.
+ *
+ * Every field is optional; supply only what your application can actually
+ * establish for THIS call.
+ */
+export interface VisiqIdentity {
+	/**
+	 * Principals this call is authorised to act for, established through a channel
+	 * the untrusted party cannot author (an IdP/session assertion, your request
+	 * context, a verification tool's RESULT).
+	 *
+	 * This is the ONLY field that writes `input.session.identity.attested_subjects`
+	 * — the set a binding rule GRANTS on. Never put a model-derived principal here.
+	 */
+	attested?: string[];
+	/**
+	 * Principals the CONVERSATION merely asserted (the model read a name out of
+	 * user text). Grants nothing; it exists so a rule can see the divergence from
+	 * `attested` rather than be blind to it.
+	 */
+	claimed?: string[];
+	/**
+	 * The human this action ACTS UPON (`write/subject_id`) — the subject a binding
+	 * rule checks against the attested set. Falls back to
+	 * `normalized.write.subject_id` when omitted.
+	 */
+	subjectId?: string;
+}
+/**
+ * A per-call resolver. Called ONCE PER GOVERNED EVALUATION, so an
+ * agent-per-request server can read its own request-scoped context (its
+ * AsyncLocalStorage, its framework's request object) inside the callback and
+ * return a different principal per call — the shape a static object cannot
+ * express.
+ *
+ * It must not throw; if it does, the throw is reported and the event carries NO
+ * identity (see {@link makeIdentityResolver}).
+ */
+export type VisiqIdentityResolver = () => VisiqIdentity | undefined | null;
+/** What `VisiqOptions.identity` accepts: a fixed attestation, or a per-call resolver. */
+export type VisiqIdentityOption = VisiqIdentity | VisiqIdentityResolver;
 export interface VisiqOptions {
 	/**
 	 * Agent identity. Optional — resolution order is this option →
@@ -23,6 +135,52 @@ export interface VisiqOptions {
 	 * for a stable, rule-friendly name.
 	 */
 	agentId?: string;
+	/**
+	 * Explicit SESSION key for sequence-aware rules (`input.session.*`), overriding
+	 * the conversation id this wrapper otherwise reads from LangChain's own config
+	 * (`configurable.thread_id`, then `configurable.session_id`).
+	 *
+	 * Set it when the host knows the conversation boundary and LangChain does not.
+	 * LEAVE IT UNSET for an agent-per-request server: a fixed value there would
+	 * fuse every request in the process into one ever-growing session, which is the
+	 * opposite failure to the one this resolution fixes — accumulating evidence
+	 * across unrelated users rather than losing it between turns of one.
+	 */
+	sessionId?: string;
+	/**
+	 * IDENTITY ATTESTATION for every governed call this wrap makes — the seam that
+	 * populates `input.session.identity.attested_subjects`, the set an
+	 * identity-binding rule GRANTS on.
+	 *
+	 * Accepts either a fixed attestation or, preferably, a RESOLVER called once
+	 * per governed evaluation so an agent-per-request server can read its own
+	 * request context per call:
+	 *
+	 * ```ts
+	 * visiq(agent, {
+	 *   identity: () => {
+	 *     const req = requestContext.getStore();          // YOUR request ALS
+	 *     return req ? { attested: [req.userId], subjectId: req.targetUserId } : undefined;
+	 *   },
+	 * });
+	 * ```
+	 *
+	 * ⚠️ **VisIQ CANNOT VERIFY THIS.** The harness runs inside your process, so
+	 * `attested` is an assertion BY YOUR APPLICATION — recorded, folded and
+	 * rule-matchable, but never independently checked by the control plane. It is
+	 * therefore yours to source from a channel the untrusted party cannot author
+	 * (an IdP/session assertion, your request context, a verification tool's
+	 * RESULT). A principal the MODEL read out of the conversation belongs in
+	 * `claimed`, which grants nothing and exists so a rule can see the divergence.
+	 * A caller that cannot tell the two apart must pass NEITHER.
+	 *
+	 * Leaving it unset is safe and is the default: `attested_subjects` stays empty
+	 * and any identity-binding rule denies — the fail-closed direction. Values are
+	 * bounded to the runtime's own limits (≤32 entries of ≤255 chars) so an
+	 * oversized principal cannot throw out of `evaluate()` and fail the whole
+	 * process OPEN.
+	 */
+	identity?: VisiqIdentityOption;
 	/** Backend API key. Falls back to VISIQ_API_KEY env var. */
 	apiKey?: string;
 	/** Backend endpoint URL. Falls back to VISIQ_ENDPOINT env var. */