@surph_ai/sdk 0.0.21 → 0.0.22

package/index.js

@@ -321,7 +321,7 @@ program.command('publish')
       })
     
       const { payload } = await resp.json()
-      console.log('\nSurph tool registered. ')
+      console.log(`\nSurph tool registered. To view, visit:\n\nhttps://surph.ai/tool/${slug}\n`)
       return
     }
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@surph_ai/sdk",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "",
   "main": "index.js",
+  "types": "./types.d.ts",
   "publishConfig": {
     "access": "public"
   },

package/scaffold/tool/tools/index.ts

@@ -1,9 +1,16 @@
 // Your tools code goes here. When ready, export
 // the tool name in exports at bottom of this file
 // as shown in this demo code:
+import type { ToolHandler, ToolContext, User } from '@surph_ai/sdk';
 
-const demoTool = (args: Record<string, any>) => {
-  return `This is a sample tool: ${JSON.stringify(args)}. Remove this tool and replace it with your own.`
-}
+type YourToolArgs = {
+  // your custom tool args goes here
+};
 
-export default demoTool
+type ToolArgs = YourToolArgs;
+
+const handler: ToolHandler<ToolArgs> = async ({ args, user, context }) => {
+  // your custom tool code goes here
+};
+
+export default handler;

package/toolserver/chat.js

@@ -46497,6 +46497,33 @@ var require_customTool = __commonJS({
   "server/shared/tools/customTool.js"(exports2, module2) {
     var { SURPH_RPC_URL } = require_config();
     var TOOL_TIMEOUT_MS = 60 * 1e3;
+    var WEB_API_BASE = process.env.SURPH_ENV === "aws" ? "https://surph.ai" : "http://localhost:3000";
+    async function refreshGoogleOauthViaWeb(userId) {
+      const internalToken = process.env.SURPH_INTERNAL_TOKEN;
+      if (!internalToken) {
+        console.warn("[customTool] SURPH_INTERNAL_TOKEN not set; skipping Google token refresh");
+        return null;
+      }
+      try {
+        const res = await fetch(`${WEB_API_BASE}/api/oauth/google/refresh`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-Internal-Token": internalToken
+          },
+          body: JSON.stringify({ userId })
+        });
+        if (!res.ok) {
+          console.warn(`[customTool] refresh endpoint returned HTTP ${res.status}`);
+          return null;
+        }
+        const json2 = await res.json().catch(() => null);
+        return json2?.oauth || null;
+      } catch (err) {
+        console.warn("[customTool] refresh endpoint call failed:", err.message);
+        return null;
+      }
+    }
     function validateCustomTool(entry) {
       if (!entry || typeof entry !== "object") {
         return { ok: false, reason: "not an object" };
@@ -46556,11 +46583,19 @@ var require_customTool = __commonJS({
       if (!Array.isArray(userTools)) return null;
       return userTools.find((t) => t && t.name === name) || null;
     }
-    async function executeCustomTool({ name, args, user, tools }) {
+    async function executeCustomTool({ name, args, user, tools, contextSlug = null }) {
       const definition = findCustomToolDefinition(tools, name);
       if (!definition) {
         return { error: `Custom tool '${name}' not found on user profile` };
       }
+      let effectiveOauth = user?.oauth || null;
+      if (user?.oauth?.google?.refreshToken) {
+        const userId = user.id || user._id;
+        if (userId) {
+          const fresh = await refreshGoogleOauthViaWeb(userId);
+          if (fresh) effectiveOauth = fresh;
+        }
+      }
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), TOOL_TIMEOUT_MS);
       try {
@@ -46570,9 +46605,10 @@ var require_customTool = __commonJS({
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({
             name,
-            args: args || {},
             tool: definition,
-            user: user ? { id: user.id || user._id, username: user.username } : null
+            context: contextSlug || null,
+            args: args || {},
+            user: user ? { id: user.id || user._id, username: user.username, oauth: effectiveOauth || {} } : null
           }),
           signal: controller.signal
         });
@@ -46658,7 +46694,7 @@ var require_executeTool = __commonJS({
       // 'deleteFile'
     ]);
     var executeTool = async (name, args, context = {}) => {
-      const { runtime = "remote", session } = context;
+      const { runtime = "remote", session, contextSlug = null } = context;
       console.log(`
 
 server/chat/executeTool.js: EXECUTE TOOL: ${session}
@@ -46709,7 +46745,7 @@ server/chat/executeTool.js: EXECUTE TOOL: ${session}
         default: {
           const userTools = session?.user?.tools;
           if (findCustomToolDefinition(userTools, name)) {
-            return await executeCustomTool({ name, args, user: session?.user, tools: userTools });
+            return await executeCustomTool({ name, args, user: session?.user, tools: userTools, contextSlug });
           }
           return { error: `Unknown tool: ${name}` };
         }
@@ -94676,6 +94712,9 @@ Always use absolute paths for file operations. When the user asks to create a fi
         runtime: "remote",
         projectPath: workingDirectory,
         session,
+        // Currently-selected context slug, forwarded to custom tools so their RPC
+        // knows which context the invocation was scoped to.
+        contextSlug: params?.context?.slug || params?.currentContextSlug || null,
         // Passed to tools that emit real-time SSE frames (e.g. searchContext
         // → `references.added`). Null on paths where no stream is bound.
         outputStream

package/toolserver/routes/tool.js

@@ -16,12 +16,12 @@ const loadTool = () => import(toolsPath).then((mod) => mod.default)
 
 const router = Router()
 
-const handler = async (args, tool) => {
-  console.log('HANDLER: ' + JSON.stringify(Object.keys(tool)))
+const handler = async (event, tool) => {
+  const { args, context, user } = event
   let payload = null
   let errorMsg = null
   try {
-    payload = await tool(args)
+    payload = await tool({ args, context, user })
   } catch (error) {
     errorMsg = error instanceof Error ? error.message : String(error)
   } finally {
@@ -88,22 +88,16 @@ router.get('/test', async (req, res, next) => {
 })
 
 router.post('/custom', async (req, res, next) => {
-  // console.log('TOOL CALL: ' + JSON.stringify(req.body))
   try {
-    const { name, args, tool, user = null } = req.body;
-    // console.log('TOOL CALL: ' + name)
-    // console.log('TOOL ARGS: ' + JSON.stringify(args))
-
+    const { name, args, tool, user = null, context = null } = req.body;
     if (process.env.SURPH_TOOL !== tool.slug) {
       throw new Error(`Invalid tool ${tool.slug}. Check .env file.`)
     }
 
     const tools = await loadTool()
-    const response = await handler(args, tools)
-    // console.log('TOOL RESP: ' + JSON.stringify(response))
+    const response = await handler({ args, context, user }, tools)
     res.json({ response })
   } catch (error) {
-    // console.log('TOOL ERR: ' + error.message)
     res.json({
       response: {
         success: false,

package/types.d.ts

@@ -0,0 +1,63 @@
+// Type definitions for @surph_ai/sdk
+// These describe the runtime contract the tool server hands to each tool's default export.
+
+export type OAuthProvider = 'google' | 'github' | (string & {});
+
+export interface GoogleOAuth {
+  accessToken: string;
+  refreshToken?: string;
+  /** ISO-8601 timestamp for when accessToken expires. */
+  expiresAt: string;
+  /** OAuth scopes granted by the user. */
+  scopes: string[];
+  /** ISO-8601 timestamp for when the user first connected the provider. */
+  connectedAt: string;
+}
+
+export interface UserOAuth {
+  google?: GoogleOAuth;
+  [provider: string]: unknown;
+}
+
+export interface UserAuth {
+  type: OAuthProvider;
+  /** Provider-issued stable identifier for the user (e.g. Google 'sub'). */
+  id: string;
+}
+
+export interface User {
+  _id: string;
+  firstName?: string;
+  lastName?: string;
+  email: string;
+  username: string;
+  avatar?: string;
+  tags?: string[];
+  following?: string[];
+  notifications?: unknown[];
+  type?: 'claimed' | 'anonymous' | (string & {});
+  auth?: UserAuth;
+  timestamp?: string;
+  lastVisit?: string;
+  identifiers?: string[];
+  tools?: string[];
+  oauth?: UserOAuth;
+}
+
+/**
+ * Per-invocation context. Currently opaque — populated by the caller (chat
+ * server, deployed harness, etc.). Cast to a more specific shape inside the
+ * tool if you know what your caller sends.
+ */
+export type ToolContext = Record<string, unknown> | null;
+
+export interface ToolHandlerInput<TArgs = Record<string, unknown>> {
+  args: TArgs;
+  context: ToolContext;
+  user: User;
+}
+
+export type ToolHandler<
+  TArgs = Record<string, unknown>,
+  TResult = unknown,
+> = (input: ToolHandlerInput<TArgs>) => Promise<TResult> | TResult;