@naswerks/periscope 1.0.0 → 1.0.1

package/src/gate/decision.ts

@@ -0,0 +1,173 @@
+/**
+ * What a decision about a tool call is, and how an unrecognised one is read.
+ *
+ * The shape is the SDK's `PermissionResult`, field for field. Not a shape of this package's own
+ * that happens to mean the same thing: the host's own local gate returns the same type, and a
+ * `canUseTool` implementation would return it directly, so a second spelling would need a
+ * translation in the one place a translation buys nothing. The SDK's word wins, exactly.
+ *
+ * The SDK documentation page names `PermissionResultDeny`, which the shipped `sdk.d.ts` does not
+ * declare (`grep -c PermissionResultDeny` returns 0). The docs page additionally states
+ * `{allow: false, reason}`, which does not exist either. Anything written that way fails to
+ * compile or, worse, type-widens.
+ *
+ * A decider returns `unknown`, deliberately. A decision arriving from a controller was never seen
+ * by this build's compiler — it is a value off a wire, from a peer that may be newer than this host.
+ * Typing the decider as returning a `Decision` would make the compiler assert a fact only the
+ * runtime can establish, and the unknown-decision rule below exists precisely because that fact is
+ * sometimes false. So the type says `unknown` and `readDecision` is the total function that narrows
+ * it — the honesty is in the signature, not in a comment.
+ */
+
+/**
+ * What a decision about one tool call says.
+ *
+ * `allow` may rewrite the call's arguments through `updatedInput`. The model is never told that
+ * happened — observed on a real session — so a rewrite is invisible from the transcript's side.
+ */
+export type Decision =
+  | { readonly behavior: 'allow'; readonly updatedInput?: Record<string, unknown> }
+  | { readonly behavior: 'deny'; readonly message: string; readonly interrupt?: boolean };
+
+/** What a decider is asked about. Everything the hook knows, in this package's own terms. */
+export interface DecisionRequest {
+  readonly toolName: string;
+  readonly toolUseId: string;
+  readonly toolInput: unknown;
+  /**
+   * The agent's own session id, read off the hook input. Not the controller's handle.
+   *
+   * Read `sessionKey` below before using this to correlate anything. This value is minted by the
+   * agent at `system/init`; every frame on the link is keyed by the controller's handle instead. So
+   * a decision request identified only by this arrives naming an id the controller may never have
+   * seen — a session that dies during start-up never mints one at all, and the first transitions of
+   * every session carry `null` here. Correlating on it is a correlation that silently fails exactly
+   * when the session is in trouble, which is when a decision matters most.
+   */
+  readonly sessionId: string;
+  /**
+   * The controller's handle — the same string every wire frame for this session is keyed by.
+   *
+   * This is the field to correlate on, and it exists because nothing else here could. The gate is
+   * the second transport: it is an ordinary HTTP POST to a URL nothing on the wire announces, so the
+   * body is the only place the two transports can be tied together. Without it a controller has to
+   * build an agent-id index and answer non-2xx for any id it has not seen yet.
+   *
+   * The host supplies it; it is never read from the agent's input, because the agent has no idea
+   * what its controller calls it.
+   */
+  readonly sessionKey: string;
+  readonly cwd: string;
+  /**
+   * The subagent this call came from, or null on the main thread.
+   *
+   * `agent_id` is the field that distinguishes a subagent call — `agent_type` is also present on the
+   * main thread of a session started with `--agent`, so branching on the type alone would read a
+   * main-thread call as a subagent one.
+   */
+  readonly agentId: string | null;
+  readonly agentType: string | null;
+}
+
+/**
+ * Answers one tool call. Returns `unknown` — see this file's header.
+ *
+ * The `signal` aborts when the surrounding turn is cancelled. A decider that reaches a controller
+ * passes it through so a cancelled turn does not leave a request in flight.
+ */
+export type Decider = (request: DecisionRequest, signal: AbortSignal) => Promise<unknown>;
+
+/**
+ * A decision read from an untrusted value: either one this build understands, or the raw payload.
+ *
+ * The raw payload is preserved rather than discarded. A host that silently drops what it did not
+ * understand makes a controller-side bug invisible on the only side that could have seen it — the
+ * controller believes it answered, the tool is blocked, and nothing anywhere says why.
+ */
+export type DecisionReading =
+  | { readonly recognised: true; readonly decision: Decision }
+  | { readonly recognised: false; readonly raw: string };
+
+/**
+ * How much of an unrecognised payload is carried into the trace.
+ *
+ * Bounded because the value goes into a transition that is retained and may cross the wire, and an
+ * unbounded field there is a way for a peer to fill this host's memory. Truncation is marked, so a
+ * reader can tell a short payload from a clipped one.
+ */
+const RAW_PAYLOAD_LIMIT = 512;
+
+/** The raw value as one line, bounded and marked. Never throws — a cyclic value is still evidence. */
+export function describeRaw(raw: unknown): string {
+  let text: string;
+  try {
+    text = raw === undefined ? 'undefined' : JSON.stringify(raw);
+    if (text === undefined) text = String(raw);
+  } catch {
+    // A cyclic or otherwise unserialisable payload still tells the reader its type, which is more
+    // than nothing and is the whole point of preserving it.
+    text = `[unserialisable ${typeof raw}]`;
+  }
+  return text.length > RAW_PAYLOAD_LIMIT ? `${text.slice(0, RAW_PAYLOAD_LIMIT)}…[truncated]` : text;
+}
+
+/**
+ * Read an untrusted value as a decision. Total: every input produces a reading.
+ *
+ * A value this build has never seen is never an allow. A controller running ahead of a host, a
+ * decision tier added later, a rolled-back deploy — each produces a `behavior` this code does not
+ * know, and the only safe reading of "I do not understand your answer" is that no answer was given.
+ * Borrowed from the Agent Client Protocol's `RequestPermissionOutcome::Other`, whose rule is that an
+ * agent which does not understand an outcome MUST NOT treat it as approval.
+ *
+ * It is refused here, by the gate, rather than at the transport. A strict codec could reject the
+ * frame instead — but then the gate never runs, and the tool's fate depends on a parse error rather
+ * than on a policy act with a receipt.
+ */
+export function readDecision(raw: unknown): DecisionReading {
+  if (typeof raw !== 'object' || raw === null) return { recognised: false, raw: describeRaw(raw) };
+
+  const candidate = raw as {
+    behavior?: unknown;
+    message?: unknown;
+    updatedInput?: unknown;
+    interrupt?: unknown;
+  };
+
+  if (candidate.behavior === 'allow') {
+    const updatedInput = candidate.updatedInput;
+    // An `allow` whose updatedInput is present but not an object is not an allow with the field
+    // dropped: it is a decision this build cannot carry out, and carrying out the half it
+    // understood would run the tool with arguments nobody approved.
+    if (updatedInput === undefined) return { recognised: true, decision: { behavior: 'allow' } };
+    if (typeof updatedInput !== 'object' || updatedInput === null || Array.isArray(updatedInput)) {
+      return { recognised: false, raw: describeRaw(raw) };
+    }
+    return {
+      recognised: true,
+      decision: { behavior: 'allow', updatedInput: updatedInput as Record<string, unknown> },
+    };
+  }
+
+  if (candidate.behavior === 'deny') {
+    // `message` is required on a deny by the SDK's own type. A deny without one would reach the
+    // model as a blocked call with no stated reason, which is the silent refusal this package
+    // forbids everywhere else — so it is unrecognised rather than quietly given a default.
+    if (typeof candidate.message !== 'string' || candidate.message.length === 0) {
+      return { recognised: false, raw: describeRaw(raw) };
+    }
+    const interrupt = candidate.interrupt;
+    if (interrupt !== undefined && typeof interrupt !== 'boolean')
+      return { recognised: false, raw: describeRaw(raw) };
+    return {
+      recognised: true,
+      decision: {
+        behavior: 'deny',
+        message: candidate.message,
+        ...(interrupt === undefined ? {} : { interrupt }),
+      },
+    };
+  }
+
+  return { recognised: false, raw: describeRaw(raw) };
+}

package/src/gate/escalate.ts

@@ -0,0 +1,164 @@
+/**
+ * Asking a controller. The one place this package makes an outbound decision request.
+ *
+ * The status is discriminated before the body is read, and that order is the whole file. A client
+ * that parses first and branches second turns a 500 carrying a perfectly valid problem-details body
+ * into an object with no `allow` field, whose falsy value renders as a refusal somebody made. That
+ * is a controller outage impersonating a human decision — nobody had said no, and the trace said
+ * somebody had. Reading `status` first makes that shape unwritable.
+ *
+ * The transport is injected and structural. A minimal `{status, text()}` shape rather than the DOM
+ * `Response` type: the global `fetch` satisfies it, a test double satisfies it without a server, and
+ * nothing here acquires a dependency on a browser lib for a package that runs on a server.
+ */
+import { certificateRemedy, describeFailure, isCertificateRefusal } from '../core/failure.js';
+import type { ControllerCredential } from '../control/credential.js';
+import type { Decider, DecisionRequest } from './decision.js';
+
+/** Just enough of a response to decide on it. `fetch`'s own `Response` satisfies this. */
+export interface EscalationResponse {
+  readonly status: number;
+  text(): Promise<string>;
+}
+
+export type EscalationTransport = (
+  url: string,
+  init: {
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+    readonly signal: AbortSignal;
+  },
+) => Promise<EscalationResponse>;
+
+export interface EscalationOptions {
+  /** Where the controller answers. Supplied by the embedder; never derived here. */
+  readonly url: string;
+  readonly transport: EscalationTransport;
+  /** Sent verbatim, on every request. For a scheme whose value does not change. */
+  readonly headers?: Record<string, string>;
+  /**
+   * The credential this host presents on each decision request. Resolved per request.
+   *
+   * Why it is a credential and not a header. The static `headers` above cannot carry a bearer
+   * token: a token is refreshed on a schedule this module does not know, so a value captured once
+   * would be presented for the life of the host and start failing silently at the first expiry —
+   * as an outage, on every tool call, which is the failure shape this whole file is written against.
+   * The same seam the link uses is asked again here, and it hands back a live value.
+   *
+   * Its failure posture is the opposite of the link's, deliberately. The link connects with no
+   * headers when its credential refuses — a stated decision, on the ground that a version without
+   * identity is better than one pretending to have a scheme. That reasoning does not transfer here.
+   * The link carries observations; this endpoint decides whether a tool runs. An unauthenticated
+   * request to it is an unauthenticated permission decision, and anyone who can reach the URL can
+   * answer for the agent. So a credential that refuses is an outage and the tool does not run — the
+   * gate's own invariant, applied to the gate's own transport. Two transports, two postures, and the
+   * difference is what each one can be used to do.
+   *
+   * Absent means no credential is presented, which is the previous behaviour and stays available for
+   * an embedder whose endpoint is reachable only from inside its own network.
+   *
+   * The precondition: a credential that refuses is not a quieter credential — it is an outage on
+   * every tool call, so the option must be omitted rather than filled with a placeholder when there
+   * is no identity. `bin/periscope.ts` does exactly that, and the composition is the contract.
+   *
+   * What this package can present is narrower than what a controller may require. `identity/`
+   * implements the authorization-code, refresh-token and device-code grants — every one of which
+   * mints a delegated user token. There is no client-credentials grant here, so this host cannot
+   * obtain an app-only token at all, and `Authorization` carries one header, so it cannot present a
+   * second scheme selector alongside the bearer. A controller that admits only a machine app role
+   * therefore refuses both postures — a configured host with a user token and an unconfigured host
+   * with none — and it refuses them at the door, fail-closed. Nothing in this file grants this host
+   * a machine identity, and a reader should not infer from the presence of this option that one
+   * exists.
+   */
+  readonly credential?: ControllerCredential;
+}
+
+/**
+ * Thrown for every way the ask failed, as distinct from a decision that said no.
+ *
+ * It is an error rather than a returned value because the gate's contract is that the decider
+ * returns whatever the controller said; "the controller said nothing" is not something it said.
+ * The gate turns this into `permission-decision-unavailable` — an outage, never a denial.
+ */
+export class EscalationUnavailable extends Error {
+  constructor(detail: string) {
+    super(detail);
+    this.name = 'EscalationUnavailable';
+  }
+}
+
+/**
+ * A decider that asks a controller over HTTP.
+ *
+ * Returns the parsed body as `unknown`: reading it as a decision is `readDecision`'s job, and a
+ * well-formed answer this build does not recognise must reach the gate to be refused by the gate.
+ *
+ * The two failure kinds are split on purpose, and the split is not obvious.
+ *   - A non-2xx, a transport error, or a body that is not JSON is an outage. The controller did not
+ *     answer, or answered something that is not an answer. A controller-side fix.
+ *   - Valid JSON that is not a decision this build knows is not handled here. It is returned intact
+ *     and the gate refuses it as unrecognised. A controller-version fix.
+ * Malformed JSON is an outage rather than an unrecognised decision because version skew produces a
+ * *different* decision, never a broken one.
+ */
+export function escalatingDecider(options: EscalationOptions): Decider {
+  return async (request: DecisionRequest, signal: AbortSignal): Promise<unknown> => {
+    // ---- The credential, before the request exists. A refusal here never becomes a request: an
+    // unauthenticated ask is not a quieter version of an authenticated one, it is a different act.
+    const authorization: Record<string, string> = {};
+    if (options.credential !== undefined) {
+      const authorized = await options.credential.authorize();
+      if (!authorized.ok) {
+        throw new EscalationUnavailable(
+          `this host has no credential to present on a decision request for ${request.toolName} ` +
+            `(${authorized.refusal.reason}: ${authorized.refusal.detail}). The request was NOT sent: ` +
+            `an unauthenticated permission decision is one anybody who can reach the endpoint could ` +
+            `answer, so the gate treats this as an outage and the tool does not run`,
+        );
+      }
+      authorization[authorized.value.header] = authorized.value.value;
+    }
+
+    let response: EscalationResponse;
+    try {
+      response = await options.transport(options.url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...(options.headers ?? {}), ...authorization },
+        body: JSON.stringify(request),
+        signal,
+      });
+    } catch (error) {
+      const why = describeFailure(error);
+      throw new EscalationUnavailable(
+        isCertificateRefusal(error)
+          ? `the decision request to ${options.url} was refused at TLS (${why}). ${certificateRemedy('the decision endpoint')}`
+          : `the decision request to ${options.url} did not complete: ${why}`,
+      );
+    }
+
+    // ---- Status first. Nothing below this line has read the body. ----
+    if (response.status < 200 || response.status >= 300) {
+      throw new EscalationUnavailable(
+        `the controller answered ${response.status} to a decision request for ${request.toolName}; ` +
+          'the body was not read, because a body that parses is not an answer that was given',
+      );
+    }
+
+    let body: string;
+    try {
+      body = await response.text();
+    } catch (error) {
+      throw new EscalationUnavailable(`the decision response body could not be read: ${String(error)}`);
+    }
+
+    try {
+      return JSON.parse(body) as unknown;
+    } catch {
+      throw new EscalationUnavailable(
+        `the controller answered ${response.status} with a body that is not JSON (${body.length} bytes)`,
+      );
+    }
+  };
+}