dreamer 0.0.0-sandbox-20251210004407 → 0.0.0-sandbox-20260105024945

package/dist/template/CLAUDE.md

@@ -0,0 +1,560 @@
+# High-level Architecture
+This application consists of a react frontend located in `src/App.tsx` and a backend
+located in `src/server.ts`. The server is responsible for calling tools and persisting data.
+The frontend calls functions on the server and does not persist any data of its own. It must
+not use browser storage like `localStorage`; all persistent state should live in the server's
+KV store. The frontend also must not call any remote APIs other than those defined in
+`src/server.ts`.
+
+The frontend has an SDK and helpers available via the `@dev-agents/sdk-client` package.
+
+The server has an SDK and helpers available to it via the `@dev-agents/sdk-server` package. The server also has access to tools defined in `sdk-helpers/tools.ts` (these are
+NOT available to the frontend).
+
+Only edit files in the `src` directory.
+
+# Server
+The server is running in bun environment. It is composed of entry-points, which can
+call tools, and persist data using the KV-store.
+
+## Entry-points
+The server defines its entry points using the `serverFunction` and `serverGetterFunction` helpers from `@dev-agents/sdk-server`. 
+These are functions that can be called from the frontend. Parameter schemas cannot use `Type.Optional`; if a
+field may be omitted, use `Type.Union` with `Type.Null()` instead (e.g.,
+`foo: Type.Union([Type.String(), Type.Null()])`).
+
+- `serverGetterFunction` - creates functions for read functions, like getting the value from the KV-store.
+  Specify keys that should cause a refetch on this function in the `keyDependencies` array so that the client
+  can be reactive to state changes. Do not do things with side-effects in these functions. These are analagous 
+  to HTTP GET methods.
+- `serverFunction` - creates a server function for mutations, things that have side-effects. These are analagous
+  to HTTP POST methods.
+
+
+e.g. a server function for setting the user's city in a weather application that can be called from the frontend:
+
+```ts
+export const setUserLocation = serverFunction({
+  description: "Sets the user's location",
+  // The type of the parameter the client sends.
+  params: Type.Object({
+    location: Type.String({ minLength: 1, description: "The user's location as a geocodable string e.g. San Francisco, CA" }),
+  }),
+  execute: async (sdk: ServerSdk, { location }) => {
+    await  await sdk.setValue("userLocation", location);
+  },
+});
+```
+
+e.g., a server function for returning the weather in the user's location that can be called from the frontend:
+
+```ts
+export const getWeather = serverGetterFunction({
+  description: "Gets the weather at the user's location as previously provided by setUserLocation",
+  // The type of the parameter the client sends.
+  params: Type.Object({}),
+  // Have clients refetch when the "userLocation" Key's value changes.
+  keyDependencies: ["userLocation"],
+  execute: async (sdk: ServerSdk, { location }) => {
+    const userCity = await sdk.getValue<string>("userLocation");
+    const weather = await weather_api_service_getcurrentweather(
+        sdk,
+        { location: userCity },
+        Type.Object({
+          tempFahrenheit: Type.Number(), 
+          isRaining: Type.Boolean()
+        })
+    );
+    
+    return weather;
+  },
+});
+```
+
+All server functions can be called as tools by the user's sidekick or other agents. Therefore it is important to use the description field for the function and any params to explain exactly what the function does and how to call it. For example if you provide an "addNote" function which requires content in markdown format, make sure you specify that it needs markdown in the description.
+
+`main` is a special entry point (and optional) to be used for executing scheduled background work
+(if the user asks for that).
+
+e.g., a main function that can be run periodically to create a weather bulletin:
+```ts
+export const main = serverFunction({
+  // Main entry point does not take any parameters.
+  params: Type.Object({}),
+  execute: async (sdk: ServerSdk) => {
+    const cities = ["San Francisco", "New York", "London"];
+    const weatherReports = [];
+    
+    for (const city of cities) {
+      const weather = await weather_api_service_getcurrentweather(
+        sdk,
+        { location: city },
+        Type.Object({
+          tempFahrenheit: Type.Number(), 
+          isRaining: Type.Boolean(),
+          description: Type.String()
+        })
+      );
+      weatherReports.push({ city, ...weather });
+    }
+    
+    // Create a bulletin to notify the user
+    await create_agent_bulletin(
+      sdk,
+      {
+        shortMessage: `Weather update for ${cities.length} cities`,
+        attachments: weatherReports.map(report => ({
+          type: "markdown",
+          content: `**${report.city}**: ${report.tempFahrenheit}°F - ${report.description}`
+        })),
+        duration: "read_once"
+      },
+      Type.Object({})
+    );
+  },
+});
+```
+
+### TRIGGERS
+
+The triggers defining when agent functions are called are defined in `agent.yaml` in a section called `triggers:`
+
+```yaml
+triggers:
+  # Cron trigger - called automatically on schedule (defaults to 'main' entrypoint)
+  - type: cron
+    defaultSchedule: 0 */2 * * *  # Every 2 hours
+    entrypoint: checkUpdates  # Optional - defaults to 'main'
+    name: "Check for Updates"  # Optional - custom name for the trigger
+    
+  # Input trigger - called manually with input data
+  - type: input
+    contentTypes: ["text/url", "text/markdown"]
+    entrypoint: processText
+    name: "Process URLs and Markdown"  # Optional - custom name for the trigger
+  
+  # More examples
+
+```
+
+**Trigger Types:**
+- **`cron`**: Automatically called on schedule (computed in user's local timezone). If no `entrypoint` is specified, defaults to `main`. Optional `name` field provides a custom display name for the trigger.
+- **`input`**: Manually called via API or share sheet with optional input data. Requires an `entrypoint` to be specified. Optional `name` field provides a custom display name for the trigger.
+
+**Common MIME Types for Input Triggers:**
+- `text/url` or `text/uri-list` - URLs/links
+- `text/plain` - Plain text
+- `text/markdown` - Markdown  
+- `text/html` - HTML content
+
+### Input Trigger Arguments
+
+Input triggers receive arguments in this structure:
+
+```typescript
+
+export const processText = serverFunction({
+  description: "Process text and other input content",
+  params: Type.Object({}),
+  execute: async (sdk: ServerSdk, params: InputTriggerParams) => {
+    if (params.message) { // The message provides context about how to handle the content
+      console.log("User instructions:", params.message);
+    }
+
+    // Process each attachment
+    for (const attachment of params.attachments || []) {
+      if (attachment.contentType === "text/url") {
+        console.log("URL:", attachment.data);
+      } else if (attachment.contentType.startsWith("text/markdown")) {
+        console.log("Markdown:", attachment.data);
+      }
+    }
+  },
+});
+```
+
+### Testing Functions and Triggers
+
+#### Server Functions
+Use the `agent-code call-server` command to test server functions:
+
+```bash
+# Call a server function with no parameters
+agent-code call-server myFunction '{}'
+
+# Call a server function with parameters
+agent-code call-server addUser '{"name": "John", "email": "john@example.com"}'
+```
+
+#### Testing Triggers
+
+**Cron triggers** run automatically on schedule, or you can test them manually with `call-server`
+
+**Input triggers** can be tested using the same `call-server` command:
+
+```bash
+# Test an input trigger function with message and attachments
+agent-code call-server handleInput '{
+  "message": "Add this to my work reading list",
+  "attachments": [
+    {
+      "name": "Example Web Page",
+      "contentType": "text/uri-list", 
+      "data": "https://example.com"
+    }
+  ]
+}'
+```
+
+
+
+## KV Store
+The server can persist data using a simple key-value store accessed through the SDK:
+
+```ts
+// Store data
+await sdk.setValue("user_preferences", { theme: "dark", language: "en" });
+
+// Retrieve data with type safety
+const preferences = await sdk.getValue<UserPreferences>("user_preferences");
+
+// Store arrays or complex objects
+const todos = await sdk.getValue<Todo[]>("todos") || [];
+todos.push(newTodo);
+await sdk.setValue("todos", todos);
+```
+
+The KV store is scoped per agent and per user. Data persists between function calls and user sessions.
+
+## Tools
+Tools are external APIs and services that your server can call. They are defined in `sdk-helpers/tools.ts` and automatically generated based on your account's available integrations.
+
+If you need to call an external API, before using a generic function like `fetch`, you should first read `sdk-helpers/tools.ts` to see if a tool already exists for the API.
+
+### Special Tools
+
+#### Agent Bulletins
+Use `create_agent_bulletin` to notify users of important information:
+
+```ts
+await create_agent_bulletin(
+  sdk,
+  {
+    shortMessage: "Brief notification title",
+    attachments: [
+      { type: "markdown", content: "**Bold** text and [links](https://example.com)" },
+      { type: "url", content: "https://example.com" }
+    ],
+    duration: "read_once" // Currently the only option
+  });
+```
+
+## Tool Selection
+
+Explore tools with the CLI. When deciding which tools to use and how to call them, run tools directly to see real outputs. This helps you pick arguments and use the output.
+
+For accessing external data with tools, you must consult `CLAUDE-DATA-PLANNING.md` for detailed instructions on creating a data plan.
+
+```bash
+# Example: Inspect a tool's output to refine arguments and schemas
+agent-code call-tool gmail_getgmailmessages '{"labelIds":["INBOX"],"maxResults":5,"pageToken":""}'
+```
+
+Notes:
+- The params argument must be a single JSON-stringified object (quote appropriately for your shell).
+- For tools with no parameters, specify an empty json object, i.e. `{}`.
+- If a tool clearly does mututations, do not test without asking the user.
+- Use what you learn from step 1 to define precise `Type` schemas for tool outputs in your server functions.
+- You must only use `Type` and related exports from `@dev-agents/sdk-shared`. DO NOT use `@sinclair/typebox` directly.
+
+## Calling LLMs
+As part of the SDK, you have access to a general-purpose LLM for via `sdk.callLLM`. You should us this method for
+tasks like transforming text, classifying user input and so on. For example, if a tool has free-text or unknown output type,
+you can stringify and pass to to the LLM with an output schema to extract structured information.
+
+```ts
+import { yelp_get_most_popular_restaurants } from "@sdk-helpers/tools";
+
+const result: unknown = yelp_get_most_popular_restaurants(sdk, { city: "Toronto" });
+
+const { italian, chinese } = sdk.callLLM(
+  `Extract the names of italian and chinese restaraunts from this list: ${JSON.stringify(result)}`,
+  // Desired structured output schema
+  Type.Object({
+    italian: Type.Array(Type.String()),
+    chinese: Type.Array(Type.String())
+  }));
+```
+
+### The sidekick
+The sidekick is a powerful system agent which builds up in its memory a detailed view of the user, their personal connections, preferences
+and information over time. It also has access to a wide range of tools. Any time you need to perform inference with the personal context of the user in mind, you should use the sidekick via `sdk.sidekick` or `sdk.sidekickWithSchema`. For example, if you are building an agent which gets information related to the user's city you could ask the sidekick to provide a default value for that city using its existing knowledge of the user.
+
+# Client
+The frontend is a React application that communicates with the server through typed function calls. It does not directly call external APIs or persist data - all data operations go through the server. The frontend must not have any routes.
+
+The client has no routing - it's a single page application. Use React state and conditional rendering to handle different views.
+
+## UI Reactivity and State Management
+
+The UI should be reactive and performant. Follow these patterns:
+
+### Optimistic Updates
+When performing mutations, immediately update the UI before the server responds:
+```tsx
+const { mutateAsync: addTodo, isLoading } = useServerFunctionMutation<typeof addTodo>("addTodo");
+const [todos, setTodos] = useState<Todo[]>([]);
+
+const handleAdd = async (text: string) => {
+  const optimisticTodo = { id: Date.now(), text, completed: false };
+  
+  // Optimistically add to UI
+  setTodos(prev => [...prev, optimisticTodo]);
+  
+  try {
+    const realTodo = await addTodo({ text });
+    // Replace optimistic version with server response
+    setTodos(prev => prev.map(t => t.id === optimisticTodo.id ? realTodo : t));
+  } catch (error) {
+    // Revert optimistic update on failure
+    setTodos(prev => prev.filter(t => t.id !== optimisticTodo.id));
+    // Show error to user
+  }
+};
+
+### State Management Guidelines
+* Local UI State: Use React state for UI-only concerns (expanded panels, form inputs, modal visibility, loading states)
+* Server State: Use server functions for data that persists or affects multiple sessions
+* Never: Store transient UI state on the server (expanded accordions, active tabs, etc.)
+
+## Hooks
+The client SDK provides several hooks for interacting with server functions:
+
+### useServerGetter
+For reactive read operations that automatically refetch when dependencies change. Use this for data that you want to display reactively.
+
+```tsx
+import { useServerGetterFunction } from "@dev-agents/sdk-client";
+import type { getWeather } from "./server";
+
+function WeatherDisplay() {
+  // This will automatically refetch when the "userLocation" key changes
+  // (if the server function declares it as a keyDependency)
+  const { 
+    data: weather, 
+    isLoading, 
+    error 
+  } = useServerGetterFunction<typeof getWeather>("getWeather");
+  
+  if (isLoading) return <div>Loading weather...</div>;
+  if (error) return <div>Error loading weather: {String(error)}</div>;
+  if (!weather) return <div>No weather data</div>;
+  
+  return (
+    <div className="weather-card">
+      <h3>Current Weather</h3>
+      <p>Temperature: {weather.tempFahrenheit}°F</p>
+      <p>{weather.isRaining ? "It's raining" : "No rain"}</p>
+    </div>
+  );
+}
+```
+
+### useServerFunctionMutation
+For calling server functions.
+
+```tsx
+import { useServerFunctionMutation } from "@dev-agents/sdk-client";
+import type { createTodo } from "./server";
+
+function AddTodo() {
+  const [text, setText] = useState("");
+  
+  const { 
+    mutateAsync: createTodo,
+    isLoading
+  } = useServerFunctionMutation<typeof createTodo>("createTodo");
+  
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    await createTodo({ text });
+    setText("");
+  };
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <input 
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        disabled={isLoading}
+      />
+      <button type="submit" disabled={isLoading}>
+        {isLoading ? "Adding..." : "Add Todo"}
+      </button>
+    </form>
+  );
+}
+```
+
+You can also use it to query data:
+
+```tsx
+const { data, isLoading, mutate: getTodos } = useServerFunctionMutation<typeof getTodos>("getTodos");
+const { mutate: addTodo, isLoading: isAdding } = useServerFunctionMutation<typeof addTodo>("addTodo");
+
+// Refetch the data when the addTodo function is done, or when the component mounts.
+useEffect(() => {
+  if (!isAdding) {
+    getTodos();
+  }
+}, [isAdding]);
+```
+
+
+## Typing Server Function Calls
+Always import the types from your server file and use them with the hooks:
+
+```tsx
+// Import types (not the actual functions)
+import type { 
+  getTodos as _getTodos,
+  createTodo as _createTodo,
+  updateTodo as _updateTodo 
+} from "./server";
+
+// Use in hooks with string names
+const { mutateAsync: create } = useServerFunctionMutation<typeof _createTodo>("createTodo");
+```
+
+Use TypeScript's type system to ensure parameter and return types match between client and server.
+
+## User interface
+
+### UI Types
+
+The user interface defined in App.tsx will be rendered by the system either as a widget on a dashboard or as a full screen app (treat feed_item the same as full screen).
+You can tell which mode is being rendered using `renderContext.type`
+
+```tsx
+interface RenderContext {
+  type: "widget" | "app" | "feed_item";
+  data?: unknown;
+}
+
+export default function App({ renderContext }: { renderContext: RenderContext }) {
+  ...
+```
+
+When rendering as a widget, keep in mind that the containing iframe, which can vary in dimensions, will be quite small - typically 300x300 px. Show only the most salient information and use compact text sizes etc. Content in widgets can scroll vertically but only the upper part is typically visible to the user, so make sure widget content starts at the very top of the container, and avoid scrolling unless necessary.
+
+When rendering in "app" mode you are being displayed full screen but must still use responsive design as App.tsx renders across mobile and desktop devices. Do make sure that all critical features of your experience are available.
+
+Do not add taglines or a description what the product does within the UI. Only include the app name in the main view if it is an important label. Space is at a premium, use it effectively. Keep the UI focused on content and functionality. Use traditional app structures like toolbars, sidebars, and icon buttons. 
+
+### Examples
+
+Worked examples of various UI scenarios have been provided for you to consult in `examples/`, here's what's in there should you need it:
+- ReadContainerSize.tsx : shows how App.tsx can track its own dimensions using ResizeObserver when it needs to know its size across different rendering contexts, while emphasizing that responsive design should be the preferred approach.
+
+- examples/components/ : A set of standard system components, including:
+  - LoadingIcon.tsx - use this whenever content is loading. Prefer it over text or a custom icon.
+
+### Colors
+
+The app needs to render nicely in dark mode and light mode. Theme appropriate tailwind CSS is loaded in the window so you should strongly prefer to use semantic colors. Tailwind color modifiers available include:
+
+--background
+--foreground
+--card
+--card-foreground
+--popover
+--popover-foreground
+--primary
+--primary-foreground
+--secondary
+--secondary-foreground
+--muted
+--muted-foreground
+--accent
+--accent-foreground
+--destructive
+--destructive-foreground
+--border
+
+Strongly prefer semantic colors. Use explicit colors only when the user specifically asks for them. To set the foreground color for text you'd add the class `text-foreground`.
+
+Do not include a dark/light mode switcher in the UI you build - this is set by the system.
+
+### Icons
+When creating UI, do not use Emoji as decoration or interface icons.
+
+Unless otherwise specified, import and use icons in the Lucide set for a consistent appearance.
+
+### Components
+
+A set of standard system components is included in `examples/components`. Use these when possible.
+
+Unless otherwise specified by the user, import and use components from shadcn, with the default theme provided in `globals.css`.
+
+
+
+# Building
+The project includes a build script that compiles both frontend and server code:
+
+```bash
+# Build everything
+bun run build
+
+# Build only server
+bun run build --server-only
+
+# Build only frontend
+bun run build --frontend-only
+
+# Build standalone frontend
+bun run build --standalone
+```
+
+The build process:
+- Compiles TypeScript server code to `dist/server/`
+- Builds React frontend with Tailwind CSS to `dist/frontend/`
+- Keeps SDK imports external (they're provided by the runtime)
+- Bundles all other dependencies
+
+
+# Development Steps
+1. Create a data-plan for any required external data by following the steps in `CLAUDE-DATA-PLANNING.md`.
+2. Implement server functions.
+3. Verify server code typechecks and builds with `bun run typecheck` and `bun run build`
+4. Implement client app to the specifications, using the server functions for getting / mutating data from
+   KV and tools. Make liberal use of console.log messages in server and client code to help you and the developer you are pairing with to understand what's going on. Logs add virtually no overhead at runtime so err on the side of lots of logging.
+5. You can pull logs of recent agent runs to verify that things are working as expected using `agent-code logs`. `agent-code logs --run <runId>` gets logs from a specific run, you can find run IDs with `agent-code runs`. Note that you may have to ask the user to interact with the agentic app and then run `agent-code logs` to see the results. `console.log` invocations in both UI and server functions will show up in these logs.
+
+### Data Sources
+If the task requires getting information from the web, and is not information that can be obtained from another tool, first use `agent-code call-tool` with any web search or web crawling tools to try to identify a good, source or query to use in the implementation for reliably getting this information. Keep trying until you find a useable source of information, DO NOT give up and hardcode information in the app.
+
+DO NOT EVER use mock or simulated data in the application unless instructed to do so by the user.
+
+DO NOT EVER use APIs that require API keys, unless instructed to do so. Good sources will be websites that you can crawl an extract information from.
+
+If you are going to use `fetch` from a URL you MUST test the fetch results first yourself by running the appropriate `curl` command in the terminal.
+
+Repeat the steps for discovering an appropriate data source until you have found one that will work to build into the app.
+
+## Final Steps and Verification
+1. **Type Check**: Run `bun run typecheck` to verify all TypeScript types are correct (do not use any other comamand or script for typechecking)
+2. **Build**: Run `bun run build` to ensure the project compiles successfully
+3. **Client-Server Verification**: Verify that:
+   - Client is only calling functions defined by the server
+   - Function names match exactly between client and server
+   - Client properly uses generic typing with types imported from server
+4. **Push the code**: Once complete use `agent-code push` to deploy the changes. 
+
+# Product requirements doc (PRD.md)
+
+There is a file called `PRD.md` in the root directory. Unless you have been provided detailed instructions to the contrary read it and follow the instructions therein.
+
+As you make changes based on the user's instructions, you must keep `PRD.md` up to date - imagine that you have to recreate the experience from that doc only. Make it clear and comprehensive and maintain the same structure. DO NOT use this as a checklist for implementation—it should stand on its own and accurately reflects the product that was built. Always push the code with `agent-code push` before updating PRD.md
+
+# Toolchain error handling.
+IMPORTANT - any time you see an error running agent-code or bun commands that is not related to the code you are editing (e.g. authentication issues, internal service errors) DO NOT try to debug and work around it. Just tell the user what went wrong. Of course, if a problem can be addressed by changing the code (e.g. typecheck errors, imports etc) go ahead and fix.

package/dist/template/agent.yaml.example

@@ -0,0 +1,36 @@
+# Agent Configuration Template
+# This file shows the structure of agent.yaml with its configuration options
+
+agentId: your-agent-id-here
+name: Your Agent Name
+hasUi: true
+
+# UI Views configuration options
+views:
+  - type: app
+  - type: widget
+    name: Single Note
+    identifier: note-widget
+    constraints:
+      minWidth: 120
+      minHeight: 120
+      maxWidth: 480
+      maxHeight: 480
+  - type: feed
+
+# Optional triggers configuration
+triggers:
+  - type: cron
+    defaultSchedule: "0 */2 * * *"  # Every 2 hours
+    entrypoint: "main"  # Optional - defaults to 'main'
+    name: "Check for Updates"  # Optional - custom name for the trigger
+
+  - type: input
+    contentTypes: ["text/uri-list", "text/markdown"]
+    entrypoint: "processText"
+    name: "Process URLs and Markdown"  # Optional - custom name for the trigger
+
+
+# Optional tools configuration
+allowedTools: []
+requiredTools: []

package/dist/template/agent.yaml.template

@@ -0,0 +1,36 @@
+# Agent Configuration Template
+# This file shows the structure of agent.yaml with its configuration options
+
+agentId: your-agent-id-here
+name: Your Agent Name
+hasUi: true
+
+# UI Views configuration options
+views:
+  - type: app
+  - type: widget
+    name: Single Note
+    identifier: note-widget
+    constraints:
+      minWidth: 120
+      minHeight: 120
+      maxWidth: 480
+      maxHeight: 480
+  - type: feed
+
+# Optional triggers configuration
+triggers:
+  - type: cron
+    defaultSchedule: "0 */2 * * *"  # Every 2 hours
+    entrypoint: "main"  # Optional - defaults to 'main'
+    name: "Check for Updates"  # Optional - custom name for the trigger
+
+  - type: input
+    contentTypes: ["text/url", "text/markdown"]
+    entrypoint: "processText"
+    name: "Process URLs and Markdown"  # Optional - custom name for the trigger
+
+
+# Optional tools configuration
+allowedTools: []
+requiredTools: []