@rayrun/sdk 0.4.0 → 0.5.0

package/README.md

@@ -50,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

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;
@@ -243,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;
 }
@@ -291,6 +375,52 @@ export class Rayrun {
       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>>;

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,6 +113,21 @@ 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 }),
@@ -189,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.4.0",
+  "version": "0.5.0",
   "description": "Type-safe client for the Rayrun public API",
   "license": "MIT",
   "repository": {