Programmatic Tool Calls: Reputation-Based Code Caching

This launch adds a materialize-first flow for programmatic tool calling. It does exactly what production teams ask for: retrieve good code on turn one, put it in a temp workspace, reuse it on later turns, and upload what changed with execution logs.

The Flow

We keep it intentionally simple:

1. First message: call search() with top_k=5 by default.
2. Materialize mode: write those snippets to a temp directory and inject a context prompt with file paths.
3. Next messages: skip search and keep using the same temp directory.
4. Run complete: diff tempdir files against the baseline, upload changed code as new snippets, include logs.

Workspace Siloing

Pass a workspace_id for strict per-customer isolation. Retrieval and upload both stay inside that workspace namespace.

Python Example

from raysurfer import AsyncRaySurfer, AsyncProgrammaticToolCallingSession

rs = AsyncRaySurfer(api_key="...")
session = AsyncProgrammaticToolCallingSession(
    rs,
    workspace_id="acme",
    top_k=5,  # default
)

# Turn 1
ctx = await session.prepare_turn("Generate quarterly report", first_message=True)
# append ctx.context_prompt to your Anthropic system prompt

# ... run programmatic tool-calling loop ...
session.append_log("tool execution output")

# Finalize
await session.upload_changed_code("Generate quarterly report", succeeded=True)

TypeScript Example

import { RaySurfer, ProgrammaticToolCallingSession } from "raysurfer";

const rs = new RaySurfer({ apiKey: "..." });
const session = new ProgrammaticToolCallingSession(rs, {
  workspaceId: "acme",
  topK: 5, // default
});

// Turn 1
const ctx = await session.prepareTurn("Generate quarterly report", {
  firstMessage: true,
});
// append ctx.contextPrompt to your Anthropic system prompt

// ... run programmatic tool-calling loop ...
session.appendLog("tool execution output");

// Finalize
await session.uploadChangedCode("Generate quarterly report", { succeeded: true });

Why This Matters

Programmatic tool calling gives you structured control. Reputation-based caching gives you compounding speed and consistency. Together, you get an agent harness that behaves more like a system and less like a one-off prompt.

That is the product direction at Raysurfer: a private Stack Overflow for AI agents with AI maintained skills, not static developer-maintained playbooks.