@robota-sdk/agent-sdk 3.0.0-beta.1

package/dist/node/index.js

@@ -0,0 +1,521 @@
+// src/types.ts
+import { TRUST_TO_MODE } from "@robota-sdk/agent-core";
+
+// src/session.ts
+import { Session } from "@robota-sdk/agent-sessions";
+
+// src/session-store.ts
+import { SessionStore } from "@robota-sdk/agent-sessions";
+
+// src/config/config-loader.ts
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+// src/config/config-types.ts
+import { z } from "zod";
+var ProviderSchema = z.object({
+  name: z.string().optional(),
+  model: z.string().optional(),
+  apiKey: z.string().optional()
+});
+var PermissionsSchema = z.object({
+  /** Patterns that are always approved without prompting */
+  allow: z.array(z.string()).optional(),
+  /** Patterns that are always denied */
+  deny: z.array(z.string()).optional()
+});
+var EnvSchema = z.record(z.string()).optional();
+var HookDefinitionSchema = z.object({
+  type: z.literal("command"),
+  command: z.string()
+});
+var HookGroupSchema = z.object({
+  matcher: z.string(),
+  hooks: z.array(HookDefinitionSchema)
+});
+var HooksSchema = z.object({
+  PreToolUse: z.array(HookGroupSchema).optional(),
+  PostToolUse: z.array(HookGroupSchema).optional(),
+  SessionStart: z.array(HookGroupSchema).optional(),
+  Stop: z.array(HookGroupSchema).optional()
+}).optional();
+var SettingsSchema = z.object({
+  /** Trust level used when no --permission-mode flag is given */
+  defaultTrustLevel: z.enum(["safe", "moderate", "full"]).optional(),
+  provider: ProviderSchema.optional(),
+  permissions: PermissionsSchema.optional(),
+  env: EnvSchema,
+  hooks: HooksSchema
+});
+
+// src/config/config-loader.ts
+function getHomeDir() {
+  return process.env.HOME ?? process.env.USERPROFILE ?? "/";
+}
+var DEFAULTS = {
+  defaultTrustLevel: "moderate",
+  provider: {
+    name: "anthropic",
+    model: "claude-opus-4-5",
+    apiKey: void 0
+  },
+  permissions: {
+    allow: [],
+    deny: []
+  },
+  env: {}
+};
+function readJsonFile(filePath) {
+  if (!existsSync(filePath)) {
+    return void 0;
+  }
+  const raw = readFileSync(filePath, "utf-8");
+  return JSON.parse(raw);
+}
+function resolveEnvRef(value) {
+  const ENV_PREFIX = "$ENV:";
+  if (value.startsWith(ENV_PREFIX)) {
+    const varName = value.slice(ENV_PREFIX.length);
+    return process.env[varName] ?? value;
+  }
+  return value;
+}
+function resolveEnvRefs(settings) {
+  if (settings.provider?.apiKey !== void 0) {
+    return {
+      ...settings,
+      provider: {
+        ...settings.provider,
+        apiKey: resolveEnvRef(settings.provider.apiKey)
+      }
+    };
+  }
+  return settings;
+}
+function mergeSettings(layers) {
+  return layers.reduce((merged, layer) => {
+    return {
+      ...merged,
+      ...layer,
+      provider: merged.provider !== void 0 || layer.provider !== void 0 ? { ...merged.provider, ...layer.provider } : void 0,
+      permissions: merged.permissions !== void 0 || layer.permissions !== void 0 ? {
+        allow: layer.permissions?.allow ?? merged.permissions?.allow,
+        deny: layer.permissions?.deny ?? merged.permissions?.deny
+      } : void 0,
+      env: {
+        ...merged.env ?? {},
+        ...layer.env ?? {}
+      }
+    };
+  }, {});
+}
+function toResolvedConfig(merged) {
+  return {
+    defaultTrustLevel: merged.defaultTrustLevel ?? DEFAULTS.defaultTrustLevel,
+    provider: {
+      name: merged.provider?.name ?? DEFAULTS.provider.name,
+      model: merged.provider?.model ?? DEFAULTS.provider.model,
+      apiKey: merged.provider?.apiKey ?? DEFAULTS.provider.apiKey
+    },
+    permissions: {
+      allow: merged.permissions?.allow ?? DEFAULTS.permissions.allow,
+      deny: merged.permissions?.deny ?? DEFAULTS.permissions.deny
+    },
+    env: merged.env ?? DEFAULTS.env,
+    hooks: merged.hooks ?? void 0
+  };
+}
+async function loadConfig(cwd) {
+  const userSettingsPath = join(getHomeDir(), ".robota", "settings.json");
+  const projectSettingsPath = join(cwd, ".robota", "settings.json");
+  const localSettingsPath = join(cwd, ".robota", "settings.local.json");
+  const rawLayers = [
+    readJsonFile(userSettingsPath),
+    readJsonFile(projectSettingsPath),
+    readJsonFile(localSettingsPath)
+  ].filter((v) => v !== void 0);
+  const parsedLayers = rawLayers.map((raw, index) => {
+    const result = SettingsSchema.safeParse(raw);
+    if (!result.success) {
+      const paths = [userSettingsPath, projectSettingsPath, localSettingsPath].filter(
+        (_, i) => rawLayers[i] !== void 0
+      );
+      throw new Error(`Invalid settings in ${paths[index] ?? "unknown"}: ${result.error.message}`);
+    }
+    return resolveEnvRefs(result.data);
+  });
+  const merged = mergeSettings(parsedLayers);
+  return toResolvedConfig(merged);
+}
+
+// src/context/context-loader.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2, dirname, resolve } from "path";
+var AGENTS_FILENAME = "AGENTS.md";
+var CLAUDE_FILENAME = "CLAUDE.md";
+function collectFilesWalkingUp(startDir, filename) {
+  const found = [];
+  let current = resolve(startDir);
+  let atRoot = false;
+  while (!atRoot) {
+    const candidate = join2(current, filename);
+    if (existsSync2(candidate)) {
+      found.push(candidate);
+    }
+    const parent = dirname(current);
+    atRoot = parent === current;
+    if (!atRoot) {
+      current = parent;
+    }
+  }
+  return found.reverse();
+}
+function extractCompactInstructions(content) {
+  const lines = content.split("\n");
+  let capturing = false;
+  let headingLevel = 0;
+  const captured = [];
+  for (const line of lines) {
+    const headingMatch = /^(#{1,6})\s+/.exec(line);
+    if (headingMatch) {
+      if (capturing) {
+        if (headingMatch[1].length <= headingLevel) break;
+      }
+      if (/compact\s+instructions/i.test(line)) {
+        capturing = true;
+        headingLevel = headingMatch[1].length;
+        continue;
+      }
+    }
+    if (capturing) {
+      captured.push(line);
+    }
+  }
+  const result = captured.join("\n").trim();
+  return result || void 0;
+}
+async function loadContext(cwd) {
+  const agentsPaths = collectFilesWalkingUp(cwd, AGENTS_FILENAME);
+  const claudePaths = collectFilesWalkingUp(cwd, CLAUDE_FILENAME);
+  const agentsMd = agentsPaths.map((p) => readFileSync2(p, "utf-8")).join("\n\n");
+  const claudeMd = claudePaths.map((p) => readFileSync2(p, "utf-8")).join("\n\n");
+  const compactInstructions = extractCompactInstructions(claudeMd);
+  return { agentsMd, claudeMd, compactInstructions };
+}
+
+// src/context/project-detector.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { join as join3 } from "path";
+function tryReadJson(filePath) {
+  if (!existsSync3(filePath)) return void 0;
+  try {
+    return JSON.parse(readFileSync3(filePath, "utf-8"));
+  } catch {
+    return void 0;
+  }
+}
+function detectPackageManager(cwd) {
+  if (existsSync3(join3(cwd, "pnpm-workspace.yaml")) || existsSync3(join3(cwd, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (existsSync3(join3(cwd, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (existsSync3(join3(cwd, "bun.lockb"))) {
+    return "bun";
+  }
+  if (existsSync3(join3(cwd, "package-lock.json"))) {
+    return "npm";
+  }
+  return void 0;
+}
+async function detectProject(cwd) {
+  const pkgJsonPath = join3(cwd, "package.json");
+  const tsconfigPath = join3(cwd, "tsconfig.json");
+  const pyprojectPath = join3(cwd, "pyproject.toml");
+  const cargoPath = join3(cwd, "Cargo.toml");
+  const goModPath = join3(cwd, "go.mod");
+  if (existsSync3(pkgJsonPath)) {
+    const pkgJson = tryReadJson(pkgJsonPath);
+    const language = existsSync3(tsconfigPath) ? "typescript" : "javascript";
+    const packageManager = detectPackageManager(cwd);
+    return {
+      type: "node",
+      name: pkgJson?.name,
+      packageManager,
+      language
+    };
+  }
+  if (existsSync3(pyprojectPath) || existsSync3(join3(cwd, "setup.py"))) {
+    return {
+      type: "python",
+      language: "python"
+    };
+  }
+  if (existsSync3(cargoPath)) {
+    return {
+      type: "rust",
+      language: "rust"
+    };
+  }
+  if (existsSync3(goModPath)) {
+    return {
+      type: "go",
+      language: "go"
+    };
+  }
+  return {
+    type: "unknown",
+    language: "unknown"
+  };
+}
+
+// src/context/system-prompt-builder.ts
+var TRUST_LEVEL_DESCRIPTIONS = {
+  safe: "safe (read-only / plan mode \u2014 only read-access tools are available)",
+  moderate: "moderate (default mode \u2014 write and bash tools require approval)",
+  full: "full (acceptEdits mode \u2014 file writes are auto-approved; bash requires approval)"
+};
+function buildProjectSection(info) {
+  const lines = ["## Current Project"];
+  if (info.name !== void 0) {
+    lines.push(`- **Name:** ${info.name}`);
+  }
+  if (info.type !== "unknown") {
+    lines.push(`- **Type:** ${info.type}`);
+  }
+  if (info.language !== "unknown") {
+    lines.push(`- **Language:** ${info.language}`);
+  }
+  if (info.packageManager !== void 0) {
+    lines.push(`- **Package manager:** ${info.packageManager}`);
+  }
+  return lines.join("\n");
+}
+function buildToolsSection(descriptions) {
+  if (descriptions.length === 0) {
+    return "";
+  }
+  const lines = ["## Available Tools", ...descriptions.map((d) => `- ${d}`)];
+  return lines.join("\n");
+}
+function buildSystemPrompt(params) {
+  const { agentsMd, claudeMd, toolDescriptions, trustLevel, projectInfo } = params;
+  const sections = [];
+  sections.push(
+    [
+      "## Role",
+      "You are an AI coding assistant with access to tools that let you read and modify code.",
+      "You help developers understand, write, and improve their codebase.",
+      "Always be precise, follow existing code conventions, and prefer minimal changes."
+    ].join("\n")
+  );
+  sections.push(buildProjectSection(projectInfo));
+  sections.push(
+    [
+      "## Permission Mode",
+      `Your current trust level is **${TRUST_LEVEL_DESCRIPTIONS[trustLevel]}**.`
+    ].join("\n")
+  );
+  if (agentsMd.trim().length > 0) {
+    sections.push(["## Agent Instructions", agentsMd].join("\n"));
+  }
+  if (claudeMd.trim().length > 0) {
+    sections.push(["## Project Notes", claudeMd].join("\n"));
+  }
+  sections.push(
+    [
+      "## Web Search",
+      "You have access to web search. When the user asks to search, look up, or find current/latest information,",
+      "you MUST use the web_search tool. Do NOT answer from training data when the user explicitly asks to search.",
+      "Always prefer web search for: news, latest versions, current events, live documentation."
+    ].join("\n")
+  );
+  const toolsSection = buildToolsSection(toolDescriptions);
+  if (toolsSection.length > 0) {
+    sections.push(toolsSection);
+  }
+  return sections.join("\n\n");
+}
+
+// src/query.ts
+import { Session as Session2 } from "@robota-sdk/agent-sessions";
+
+// src/permissions/permission-prompt.ts
+import chalk from "chalk";
+var PERMISSION_OPTIONS = ["Allow", "Deny"];
+var ALLOW_INDEX = 0;
+function formatArgs(toolArgs) {
+  const entries = Object.entries(toolArgs);
+  if (entries.length === 0) {
+    return "(no arguments)";
+  }
+  return entries.map(([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`).join(", ");
+}
+async function promptForApproval(terminal, toolName, toolArgs) {
+  terminal.writeLine("");
+  terminal.writeLine(chalk.yellow(`[Permission Required] Tool: ${toolName}`));
+  terminal.writeLine(chalk.dim(`  ${formatArgs(toolArgs)}`));
+  terminal.writeLine("");
+  const selected = await terminal.select(PERMISSION_OPTIONS, ALLOW_INDEX);
+  return selected === ALLOW_INDEX;
+}
+
+// src/query.ts
+async function query(prompt, options) {
+  const cwd = options?.cwd ?? process.cwd();
+  const [config, context, projectInfo] = await Promise.all([
+    loadConfig(cwd),
+    loadContext(cwd),
+    detectProject(cwd)
+  ]);
+  const noopTerminal = {
+    write: () => {
+    },
+    writeLine: () => {
+    },
+    writeMarkdown: () => {
+    },
+    writeError: () => {
+    },
+    prompt: () => Promise.resolve(""),
+    select: () => Promise.resolve(0),
+    spinner: () => ({ stop: () => {
+    }, update: () => {
+    } })
+  };
+  const session = new Session2({
+    config,
+    context,
+    terminal: noopTerminal,
+    projectInfo,
+    permissionMode: options?.permissionMode ?? "bypassPermissions",
+    maxTurns: options?.maxTurns,
+    provider: options?.provider,
+    permissionHandler: options?.permissionHandler,
+    onTextDelta: options?.onTextDelta,
+    onCompact: options?.onCompact,
+    compactInstructions: context.compactInstructions,
+    systemPromptBuilder: buildSystemPrompt,
+    promptForApproval
+  });
+  return session.run(prompt);
+}
+
+// src/permissions/permission-gate.ts
+import { evaluatePermission } from "@robota-sdk/agent-core";
+
+// src/hooks/hook-runner.ts
+import { runHooks } from "@robota-sdk/agent-core";
+
+// src/tools/bash-tool.ts
+import { bashTool } from "@robota-sdk/agent-tools";
+
+// src/tools/read-tool.ts
+import { readTool } from "@robota-sdk/agent-tools";
+
+// src/tools/write-tool.ts
+import { writeTool } from "@robota-sdk/agent-tools";
+
+// src/tools/edit-tool.ts
+import { editTool } from "@robota-sdk/agent-tools";
+
+// src/tools/glob-tool.ts
+import { globTool } from "@robota-sdk/agent-tools";
+
+// src/tools/grep-tool.ts
+import { grepTool } from "@robota-sdk/agent-tools";
+
+// src/tools/agent-tool.ts
+import { z as z2 } from "zod";
+import { createZodFunctionTool } from "@robota-sdk/agent-tools";
+import { Session as Session3 } from "@robota-sdk/agent-sessions";
+function asZodSchema(schema) {
+  return schema;
+}
+var AgentSchema = z2.object({
+  prompt: z2.string().describe("Task description for the sub-agent"),
+  description: z2.string().optional().describe("Short description of what the sub-agent will do (3-5 words)")
+});
+var agentToolDeps;
+function setAgentToolDeps(deps) {
+  agentToolDeps = deps;
+}
+async function runAgent(args) {
+  if (!agentToolDeps) {
+    const result = {
+      success: false,
+      output: "",
+      error: "Agent tool not initialized \u2014 missing dependencies"
+    };
+    return JSON.stringify(result);
+  }
+  const subSession = new Session3({
+    config: agentToolDeps.config,
+    context: agentToolDeps.context,
+    projectInfo: agentToolDeps.projectInfo,
+    // No terminal needed — sub-agents don't prompt for permissions
+    terminal: {
+      write: () => {
+      },
+      writeLine: () => {
+      },
+      writeMarkdown: () => {
+      },
+      writeError: () => {
+      },
+      prompt: () => Promise.resolve(""),
+      select: () => Promise.resolve(0),
+      spinner: () => ({ stop: () => {
+      }, update: () => {
+      } })
+    },
+    // Sub-agents bypass permissions — they inherit parent's trust
+    permissionMode: "bypassPermissions"
+  });
+  try {
+    const response = await subSession.run(args.prompt);
+    const result = {
+      success: true,
+      output: response
+    };
+    return JSON.stringify(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const result = {
+      success: false,
+      output: "",
+      error: `Sub-agent error: ${message}`
+    };
+    return JSON.stringify(result);
+  }
+}
+var agentTool = createZodFunctionTool(
+  "Agent",
+  "Spawn a sub-agent with isolated context to handle a task. The sub-agent has its own conversation history and can use all tools.",
+  asZodSchema(AgentSchema),
+  async (params) => {
+    return runAgent(params);
+  }
+);
+export {
+  Session,
+  SessionStore,
+  TRUST_TO_MODE,
+  agentTool,
+  bashTool,
+  buildSystemPrompt,
+  detectProject,
+  editTool,
+  evaluatePermission,
+  globTool,
+  grepTool,
+  loadConfig,
+  loadContext,
+  promptForApproval,
+  query,
+  readTool,
+  runHooks,
+  setAgentToolDeps,
+  writeTool
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@robota-sdk/agent-sdk",
+  "version": "3.0.0-beta.1",
+  "description": "Programmatic SDK for building AI agents with Robota — provides Session, query(), built-in tools, permissions, hooks, and context loading",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "node": {
+        "import": "./dist/node/index.js",
+        "require": "./dist/node/index.cjs"
+      },
+      "default": {
+        "import": "./dist/node/index.js",
+        "require": "./dist/node/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "zod": "^3.24.0",
+    "@robota-sdk/agent-provider-anthropic": "3.0.0-beta.1",
+    "@robota-sdk/agent-core": "3.0.0-beta.1",
+    "@robota-sdk/agent-tools": "3.0.0-beta.1",
+    "@robota-sdk/agent-sessions": "3.0.0-beta.1"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.6.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --out-dir dist/node --clean",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ --ext .ts",
+    "clean": "rimraf dist"
+  }
+}