@rayrun/sdk 0.3.0 → 0.5.0

package/README.md

@@ -9,6 +9,7 @@ import { Rayrun } from '@rayrun/sdk';
 
 const rayrun = new Rayrun({ apiKey: process.env.RAYRUN_API_KEY });
 const { items: connections } = await rayrun.connections.list();
+const { items: matchingTools } = await rayrun.tools.list({ query: 'create issue' });
 ```
 
 Create keys in **Dashboard → Settings → API keys**. The plaintext is shown once.
@@ -17,6 +18,18 @@ The client covers catalog search, connection and credential setup, OAuth links,
 client policies, reusable access profiles, activity, review queues, and webhooks. Safe reads retry
 rate limits, server errors, and transient network failures; writes do not retry automatically.
 
+Inspect the effective policy applied to one connected client without reproducing policy logic in
+your application:
+
+```js
+const { items: effectivePolicy } = await rayrun.clients.listTools(clientUid, {
+  query: 'create issue',
+});
+```
+
+Each result includes the effective decision and the workspace, access-profile, or client layer that
+restricted it.
+
 ## Reuse one access ceiling across clients
 
 ```js
@@ -37,6 +50,42 @@ await rayrun.clients.setAccessProfile(clientUid, profile.uid, clientToolPolicyVe
 The effective policy is always the intersection of the workspace, profile, and client rules. A
 profile can narrow access but cannot grant something blocked by the workspace or client.
 
+## Manage hosted tool hooks
+
+Hooks are versioned TypeScript adapters hosted and sandboxed by Rayrun. Pull the generated types and
+draft, test it without a live upstream call, then create an immutable shadow or active revision.
+
+```js
+const { hook } = await rayrun.hooks.get(connectionUid, toolUid);
+
+const tested = await rayrun.hooks.test(connectionUid, toolUid, {
+  source: hook.draftSource,
+  config: hook.draftConfig,
+  arguments: { query: 'release' },
+  mockResult: { items: [] },
+});
+
+const saved = await rayrun.hooks.saveDraft(connectionUid, toolUid, {
+  source: hook.draftSource,
+  config: hook.draftConfig,
+  expectedVersion: hook.version,
+});
+
+await rayrun.hooks.deploy(connectionUid, toolUid, {
+  expectedVersion: saved.hook.version,
+  mode: 'shadow',
+});
+
+const runs = await rayrun.hooks.listRuns(connectionUid, toolUid, { limit: 25 });
+```
+
+`setDeployment` moves an active or shadow pointer to an existing compatible revision, or deactivates
+it with `revisionUid: null`. Every mutation uses `expectedVersion`; fetch and reconcile instead of
+blindly retrying a `version_conflict`. Use a full-control API key for hook writes. Read-only keys can
+inspect source, generated declarations, revision history, and deployed-run metadata; captured logs
+and errors require `hooks:write`. `RayrunApiError.diagnostics` carries compiler line and column
+details for editor and CI output.
+
 ## Stream code run-ahead
 
 A model harness that receives `execute_code` arguments incrementally can let Rayrun start eligible
@@ -92,7 +141,8 @@ const valid = verifyWebhookSignature({
 ```
 
 After verification, parse the body as `WebhookPayload`. Every event has a stable `id`, `type`, and
-`occurredAt`; its `data` shape is narrowed by `type`. Use `id` to deduplicate retries.
+`occurredAt`; its `data` shape is narrowed by `type`. Delivery is at least once, so make processing
+idempotent and deduplicate on `id`.
 For `activity.call`, `arguments` and `result` contain the captured tool payloads, or `null` when
 capture was disabled for that connection, the webhook did not opt in with
 `forwardToolPayloads: true`, or no result existed. `payloadCaptured` distinguishes a metadata-only

package/index.d.ts

@@ -51,6 +51,89 @@ export type Tool = {
   inputSchema: Record<string, unknown>;
   title: string | null;
 };
+export type ToolHookPublicContract = {
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+};
+export type ToolHookRevision = {
+  config: Record<string, JsonValue>;
+  createdAt: string;
+  publicContract: ToolHookPublicContract | null;
+  revisionNumber: number;
+  source: string;
+  sourceHash: string;
+  uid: string;
+  upstreamDefinitionHash: string;
+};
+export type ToolHook = {
+  activeRevisionStale: boolean;
+  activeRevisionUid: string | null;
+  draftConfig: Record<string, JsonValue>;
+  draftSource: string;
+  hookUid: string | null;
+  revisions: ToolHookRevision[];
+  shadowRevisionStale: boolean;
+  shadowRevisionUid: string | null;
+  target: {
+    definitionHash: string | null;
+    inputSchema: Record<string, unknown>;
+    name: string;
+    outputSchema: Record<string, unknown> | null;
+    toolUid: string;
+  };
+  types: string;
+  version: number;
+};
+export type ToolHookLogEntry = {
+  data?: JsonValue;
+  level: 'debug' | 'error' | 'info' | 'warn';
+  message: string;
+};
+export type ToolHookTestFailure = {
+  durationMs: number;
+  error: {
+    code: 'invalid_arguments' | 'invalid_outcome' | 'invalid_output' | 'runtime_error' | 'timeout';
+    message: string;
+  };
+  logs: ToolHookLogEntry[];
+  status: 'failed';
+};
+export type ToolHookBeforeTestResult =
+  | {
+      durationMs: number;
+      logs: ToolHookLogEntry[];
+      outcome:
+        | { action: 'continue'; arguments: JsonValue }
+        | { action: 'reject'; message: string; reason: string }
+        | { action: 'require_approval'; arguments: JsonValue; reason: string };
+      status: 'completed';
+    }
+  | ToolHookTestFailure;
+export type ToolHookAfterTestResult =
+  | {
+      durationMs: number;
+      logs: ToolHookLogEntry[];
+      outcome:
+        | { action: 'return'; result: JsonValue }
+        | { action: 'fail'; message: string; reason: string };
+      status: 'completed';
+    }
+  | ToolHookTestFailure;
+export type ToolHookRun = {
+  createdAt: string;
+  differsFromActive: boolean | null;
+  durationMs: number;
+  errorMessage: string | null;
+  id: string;
+  logs: ToolHookLogEntry[] | null;
+  outcome: 'approval-required' | 'continued' | 'failed' | 'rejected' | 'returned';
+  requestId: string;
+  revisionUid: string;
+  shadow: boolean;
+  stage: 'after' | 'before';
+  uid: string;
+};
 export type Client = {
   accessProfile: Pick<AccessProfile, 'name' | 'uid'> | null;
   clientName: string;
@@ -63,6 +146,27 @@ export type Client = {
   uid: string;
   userName: string;
 };
+export type ClientTool = {
+  approved: boolean;
+  clientDecision: ToolDecision | null;
+  effectiveDecision: ToolDecision;
+  effectiveReason:
+    | 'definition-unapproved'
+    | 'workspace-tool-rule'
+    | 'workspace-default'
+    | 'client-profile-tool-rule'
+    | 'client-profile-default'
+    | 'client-tool-rule'
+    | 'client-default'
+    | 'multiple-layers'
+    | 'workspace-and-client';
+  name: string;
+  riskLevel: Risk;
+  riskReason: string;
+  serviceName: string;
+  uid: string;
+  workspaceDecision: ToolDecision | null;
+};
 export type AccessProfile = {
   assignedClientCount: number;
   description: string;
@@ -222,6 +326,7 @@ export const CODE_RUN_AHEAD_META_KEY: 'io.rayrun/run-ahead-session';
 
 export class RayrunApiError extends Error {
   code: string;
+  diagnostics: Array<{ column?: number; line?: number; message: string }>;
   requestId: string | null;
   status: number;
 }
@@ -263,15 +368,62 @@ export class Rayrun {
     setPolicy(uid: string, mode: ToolAccessMode): Promise<void>;
   };
   tools: {
-    list(query?: PageQuery & { connectionUid?: string }): Promise<CursorPage<Tool>>;
+    list(query?: PageQuery & { connectionUid?: string; query?: string }): Promise<CursorPage<Tool>>;
     setPolicy(
       connectionUid: string,
       toolUid: string,
       body: { decision: ToolDecision | null; riskConfirmed?: boolean; riskOverride?: Risk | null },
     ): Promise<void>;
   };
+  hooks: {
+    deploy(
+      connectionUid: string,
+      toolUid: string,
+      body: { expectedVersion: number; mode: 'active' | 'shadow' },
+    ): Promise<{ hook: ToolHook }>;
+    get(connectionUid: string, toolUid: string): Promise<{ hook: ToolHook }>;
+    listRuns(
+      connectionUid: string,
+      toolUid: string,
+      query?: PageQuery,
+    ): Promise<CursorPage<ToolHookRun>>;
+    saveDraft(
+      connectionUid: string,
+      toolUid: string,
+      body: {
+        config?: Record<string, JsonValue>;
+        expectedVersion: number;
+        source: string;
+      },
+    ): Promise<{ hook: ToolHook }>;
+    setDeployment(
+      connectionUid: string,
+      toolUid: string,
+      body: {
+        expectedVersion: number;
+        mode: 'active' | 'shadow';
+        revisionUid: string | null;
+      },
+    ): Promise<{ hook: ToolHook }>;
+    test(
+      connectionUid: string,
+      toolUid: string,
+      body: {
+        arguments: JsonValue;
+        config?: Record<string, JsonValue>;
+        mockResult?: JsonValue;
+        source: string;
+      },
+    ): Promise<{
+      after?: ToolHookAfterTestResult;
+      before: ToolHookBeforeTestResult;
+      publicContract: ToolHookPublicContract | null;
+      sourceHash: string;
+    }>;
+  };
   clients: {
     list(query?: PageQuery): Promise<CursorPage<Client>>;
+    listTools(uid: string, query?: PageQuery & { query?: string }): Promise<CursorPage<ClientTool>>;
     setAccessProfile(
       uid: string,
       profileUid: string | null,

package/index.js

@@ -1,10 +1,11 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 
 export class RayrunApiError extends Error {
-  constructor(message, { code, requestId, status }) {
+  constructor(message, { code, diagnostics = [], requestId, status }) {
     super(message);
     this.name = 'RayrunApiError';
     this.code = code;
+    this.diagnostics = diagnostics;
     this.requestId = requestId;
     this.status = status;
   }
@@ -112,8 +113,24 @@ export class Rayrun {
       setPolicy: (connectionUid, toolUid, body) =>
         this.request('PATCH', `/connections/${connectionUid}/tools/${toolUid}/policy`, { body }),
     };
+    const toolHookPath = (connectionUid, toolUid) =>
+      `/connections/${connectionUid}/tools/${toolUid}/hook`;
+    this.hooks = {
+      deploy: (connectionUid, toolUid, body) =>
+        this.request('POST', `${toolHookPath(connectionUid, toolUid)}/deploy`, { body }),
+      get: (connectionUid, toolUid) => this.request('GET', toolHookPath(connectionUid, toolUid)),
+      listRuns: (connectionUid, toolUid, query) =>
+        this.request('GET', `${toolHookPath(connectionUid, toolUid)}/runs`, { query }),
+      saveDraft: (connectionUid, toolUid, body) =>
+        this.request('PUT', toolHookPath(connectionUid, toolUid), { body }),
+      setDeployment: (connectionUid, toolUid, body) =>
+        this.request('POST', `${toolHookPath(connectionUid, toolUid)}/deployment`, { body }),
+      test: (connectionUid, toolUid, body) =>
+        this.request('POST', `${toolHookPath(connectionUid, toolUid)}/test`, { body }),
+    };
     this.clients = {
       list: (query) => this.request('GET', '/clients', { query }),
+      listTools: (uid, query) => this.request('GET', `/clients/${uid}/tools`, { query }),
       setAccessProfile: (uid, profileUid, expectedVersion) =>
         this.request('PATCH', `/clients/${uid}/access-profile`, {
           body: { expectedVersion, profileUid },
@@ -188,6 +205,7 @@ export class Rayrun {
           problem?.error?.message ?? `Rayrun API request failed with HTTP ${response.status}.`,
           {
             code: problem?.error?.code ?? 'request_failed',
+            diagnostics: Array.isArray(problem?.diagnostics) ? problem.diagnostics : [],
             requestId: problem?.error?.requestId ?? response.headers.get('rayrun-request-id'),
             status: response.status,
           },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayrun/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Type-safe client for the Rayrun public API",
   "license": "MIT",
   "repository": {