@agentuity/claude-code 1.0.5

package/skills/agentuity-frontend/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: agentuity-frontend
+description: When working with Agentuity SDK frontend packages including @agentuity/react, @agentuity/frontend, @agentuity/auth, or @agentuity/workbench. Activates when building React components that call agents, setting up authentication, using useAPI or useWebsocket hooks, or integrating the workbench dev UI.
+version: 1.0.0
+---
+
+# Agentuity Frontend Reference
+
+Deep reference material for the Agentuity SDK frontend packages used to build web applications, React integrations, and authentication.
+
+## Package Overview
+
+| Package | Purpose |
+|---------|---------|
+| `@agentuity/react` | React hooks for calling agents (useAPI, useWebsocket) |
+| `@agentuity/frontend` | Framework-agnostic web utilities |
+| `@agentuity/auth` | Authentication (server + client) |
+| `@agentuity/workbench` | Dev UI for testing agents |
+
+## Reference URLs
+
+When uncertain, look up:
+- **SDK Source**: https://github.com/agentuity/sdk/tree/main/packages
+- **Docs**: https://agentuity.dev
+- **React Package**: https://github.com/agentuity/sdk/tree/main/packages/react/src
+- **Auth Package**: https://github.com/agentuity/sdk/tree/main/packages/auth/src
+
+---
+
+## @agentuity/react
+
+React hooks and components for Agentuity web applications.
+
+### Setup with AgentuityProvider
+
+```tsx
+import { AgentuityProvider } from '@agentuity/react';
+
+function App() {
+   return (
+      <AgentuityProvider>
+         <MyApp />
+      </AgentuityProvider>
+   );
+}
+```
+
+NOTE: The `baseUrl="http://localhost:3000"` property is only needed if using outside an Agentuity full stack project.
+
+### useAPI Hook
+
+Call agents/routes from React components with automatic type inference.
+
+```tsx
+import { useAPI } from '@agentuity/react';
+
+function ChatComponent() {
+   // For POST/mutation routes
+   const { data, invoke, isLoading, isSuccess, isError, error, reset } = useAPI('POST /agent/chat');
+
+   const handleSubmit = async (message: string) => {
+      await invoke({ message });
+   };
+
+   return (
+      <div>
+         {isLoading && <p>Loading...</p>}
+         {data && <p>Response: {data.reply}</p>}
+         {error && <p>Error: {error.message}</p>}
+         <button onClick={() => handleSubmit('Hello!')}>Send</button>
+      </div>
+   );
+}
+
+// For GET routes (auto-fetches on mount)
+function UserProfile() {
+   const { data, isLoading, isFetching, refetch } = useAPI('GET /api/user');
+   // data is fetched automatically on mount
+   // isFetching is true during refetches
+}
+```
+
+**Options:**
+```typescript
+const { data, invoke } = useAPI({
+   route: 'POST /agent/my-agent',
+   headers: { 'X-Custom': 'value' },
+});
+
+// Streaming support
+const { data, invoke } = useAPI('POST /agent/stream', {
+   delimiter: '\n',
+   onChunk: (chunk) => console.log('Received chunk:', chunk),
+});
+```
+
+### useWebsocket Hook
+
+Real-time bidirectional communication.
+
+```tsx
+import { useWebsocket } from '@agentuity/react';
+
+function LiveChat() {
+   const {
+      isConnected,
+      send,
+      close,
+      data,           // Latest message
+      messages,       // All messages array
+      clearMessages,  // Clear message history
+      error,
+      readyState
+   } = useWebsocket('/ws/chat');
+
+   // Messages are accessed via data (latest) or messages (all)
+   useEffect(() => {
+      if (data) {
+         console.log('Received:', data);
+      }
+   }, [data]);
+
+   return (
+      <div>
+         <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
+         <button onClick={() => send({ type: 'ping' })}>Ping</button>
+         <ul>
+            {messages.map((msg, i) => <li key={i}>{JSON.stringify(msg)}</li>)}
+         </ul>
+      </div>
+   );
+}
+```
+
+**Features:**
+- Auto-reconnection on connection loss
+- Message queuing when disconnected
+- Auth tokens auto-injected when AuthProvider is in tree
+- Access latest message via `data` or all via `messages` array
+
+### useAuth Hook
+
+Access authentication state.
+
+```tsx
+import { useAuth } from '@agentuity/react';
+
+function UserProfile() {
+   const { isAuthenticated, authLoading, authHeader } = useAuth();
+
+   if (authLoading) return <p>Loading...</p>;
+   if (!isAuthenticated) return <p>Please sign in</p>;
+
+   return <p>Welcome back!</p>;
+}
+```
+
+**Note:** Auth tokens are automatically injected into useAPI and useWebsocket calls when AuthProvider is in the component tree.
+
+---
+
+## @agentuity/auth
+
+First-class authentication for Agentuity projects, powered by BetterAuth.
+
+### Server Setup
+
+```typescript
+import { createAuth, createSessionMiddleware, mountAuthRoutes } from '@agentuity/auth';
+import { createRouter } from '@agentuity/runtime';
+
+// Create auth instance
+const auth = createAuth({
+   connectionString: process.env.DATABASE_URL,
+   // Optional: custom base path (default: /api/auth)
+   basePath: '/api/auth',
+});
+
+const router = createRouter();
+
+// Mount auth routes (handles sign-in, sign-up, etc.)
+router.on(['GET', 'POST'], '/api/auth/*', mountAuthRoutes(auth));
+
+// Protect routes with session middleware
+router.use('/api/*', createSessionMiddleware(auth));
+```
+
+### Agent Handler (ctx.auth)
+
+When using auth middleware, `ctx.auth` is available in agent handlers:
+
+```typescript
+import { createAgent } from '@agentuity/runtime';
+
+export default createAgent('protected-agent', {
+   handler: async (ctx, input) => {
+      // ctx.auth is null for unauthenticated requests
+      if (!ctx.auth) {
+         return { error: 'Please sign in' };
+      }
+
+      // Get authenticated user
+      const user = await ctx.auth.getUser();
+      return { message: `Hello ${user.name}` };
+   },
+});
+```
+
+### Client Setup (React)
+
+```tsx
+import { AuthProvider } from '@agentuity/react';
+
+function App() {
+   return (
+      <AuthProvider>
+         <AgentuityProvider>
+            <MyApp />
+         </AgentuityProvider>
+      </AuthProvider>
+   );
+}
+```
+
+### Integration with @agentuity/drizzle
+
+```typescript
+import { createPostgresDrizzle, drizzleAdapter } from '@agentuity/drizzle';
+import { createAuth } from '@agentuity/auth';
+import * as schema from './schema';
+
+const { db, close } = createPostgresDrizzle({ schema });
+
+const auth = createAuth({
+   database: drizzleAdapter(db, { provider: 'pg' }),
+});
+```
+
+---
+
+## @agentuity/frontend
+
+Framework-agnostic utilities for web applications.
+
+- URL building for API endpoints
+- Reconnection manager for WebSocket connections
+- Shared utilities used by @agentuity/react
+
+---
+
+## @agentuity/workbench
+
+Dev UI for testing agents during development.
+
+```typescript
+// In your main entry point
+import { welcome } from '@agentuity/workbench';
+
+// Export welcome to enable the workbench
+export { welcome };
+```
+
+The workbench provides a testing interface for your agents during local development (`bun run dev`).
+
+---
+
+## Common Patterns
+
+### Full-Stack Setup
+
+```
+src/
+├── agent/<name>/    # Agent handlers (backend)
+│   ├── agent.ts
+│   └── index.ts
+├── api/             # API routes (Hono)
+│   └── index.ts
+└── web/             # React frontend
+    ├── App.tsx
+    ├── index.tsx
+    └── components/
+```
+
+### Auth + Agent Call Pattern
+
+```tsx
+import { AuthProvider, AgentuityProvider, useAPI, useAuth } from '@agentuity/react';
+
+function App() {
+   return (
+      <AuthProvider>
+         <AgentuityProvider>
+            <ProtectedChat />
+         </AgentuityProvider>
+      </AuthProvider>
+   );
+}
+
+function ProtectedChat() {
+   const { isAuthenticated } = useAuth();
+   const { data, invoke } = useAPI('POST /agent/chat');
+
+   if (!isAuthenticated) return <SignIn />;
+
+   return (
+      <div>
+         <button onClick={() => invoke({ message: 'Hello' })}>Chat</button>
+         {data && <p>{data.reply}</p>}
+      </div>
+   );
+}
+```
+
+## Common Mistakes
+
+| Mistake | Better Approach | Why |
+|---------|-----------------|-----|
+| Adding `baseUrl` inside Agentuity project | Omit `baseUrl` | Auto-detected in full-stack projects |
+| Using `fetch` directly for agents | Use `useAPI` hook | Type inference, auth injection, loading states |
+| Manual WebSocket management | Use `useWebsocket` hook | Auto-reconnect, auth injection, message queuing |
+| Missing AuthProvider | Wrap app with AuthProvider | Required for auth token injection |

package/skills/agentuity-ops/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: agentuity-ops
+description: When working with the Agentuity CLI, cloud services (KV, Vector, Storage, Sandbox, Database, SSH), deployments, or infrastructure. Activates when running agentuity commands, managing cloud resources, deploying projects, or configuring infrastructure.
+version: 1.0.0
+---
+
+# Agentuity Ops Reference
+
+Deep reference material for the Agentuity CLI, cloud services, deployments, and infrastructure.
+
+## CLI Accuracy Contract (NON-NEGOTIABLE)
+
+**Never hallucinate CLI flags, subcommands, URLs, or outputs.**
+
+1. **Never guess** flags, subcommands, or argument order
+2. If not 100% certain, FIRST run: `agentuity <cmd> --help`
+3. **Trust CLI output over memory**
+4. **Never fabricate URLs** — read actual command output
+5. Provide **copy/paste-ready commands**
+
+## CRITICAL: Region Configuration
+
+Before suggesting `--region` flags, CHECK EXISTING CONFIG:
+
+```bash
+cat ~/.config/agentuity/config.json 2>/dev/null | grep region
+cat agentuity.json 2>/dev/null | grep region
+```
+
+- If region is configured → NO `--region` flag needed
+- If NOT configured → help user set it in config OR use `--region`
+
+## CRITICAL: Agentuity Projects Use Bun (Always)
+
+- If `agentuity.json` or `.agentuity/` exists → ALWAYS use `bun`
+- Never suggest `npm` or `pnpm` for Agentuity projects
+
+## Golden Commands
+
+| Purpose | Command |
+|---------|---------|
+| Create project | `agentuity new` (interactive) or `agentuity new --name <name>` |
+| Start dev server | `bun run dev` → read output for actual URL |
+| Deploy | `agentuity deploy` → read output for deployment URL |
+| Check auth | `agentuity auth whoami` |
+| List regions | `agentuity region list` |
+| Get CLI help | `agentuity <command> --help` |
+| Show all commands | `agentuity ai schema show` |
+
+---
+
+## Cloud Service Commands
+
+### KV (Key-Value Storage)
+
+```bash
+# Namespace management
+agentuity cloud kv list-namespaces --json
+agentuity cloud kv create-namespace <name>
+agentuity cloud kv delete-namespace <name> --json
+
+# Key operations
+agentuity cloud kv set <namespace> <key> <value> [ttl]
+agentuity cloud kv get <namespace> <key> --json
+agentuity cloud kv keys <namespace> --json
+agentuity cloud kv search <namespace> <keyword> --json
+agentuity cloud kv delete <namespace> <key> --json
+agentuity cloud kv stats --json
+```
+
+### Storage (S3-compatible)
+
+```bash
+agentuity cloud storage list --json
+agentuity cloud storage create --json
+agentuity cloud storage upload <bucket> <file> --key <path> --json
+agentuity cloud storage download <bucket> <filename> [output]
+agentuity cloud storage list <bucket> [prefix] --json
+agentuity cloud storage delete <bucket> <filename> --json
+```
+
+### Vector (Semantic Search)
+
+```bash
+agentuity cloud vector upsert <namespace> <key> --document "text" --json
+agentuity cloud vector search <namespace> "query" --limit N --json
+agentuity cloud vector get <namespace> <key> --json
+agentuity cloud vector delete <namespace> <key> --no-confirm --json
+```
+
+### Sandbox (Isolated Execution)
+
+```bash
+# Runtimes
+agentuity cloud sandbox runtime list --json
+
+# Lifecycle
+agentuity cloud sandbox run [--memory 1Gi] [--cpu 1000m] \
+  [--runtime <name>] [--name <name>] [--description <text>] \
+  -- <command>                                             # One-shot
+agentuity cloud sandbox create --json [--memory 1Gi] \
+  [--network] [--port <1024-65535>] \
+  [--runtime <name>] [--name <name>]                       # Persistent
+agentuity cloud sandbox exec <sandboxId> -- <command>
+agentuity cloud sandbox list --json
+agentuity cloud sandbox get <sandboxId> --json
+agentuity cloud sandbox delete <sandboxId> --json
+
+# File operations (default working dir: /home/agentuity)
+agentuity cloud sandbox files <sandboxId> [path] --json
+agentuity cloud sandbox cp ./local sbx_abc123:/home/agentuity
+agentuity cloud sandbox cp sbx_abc123:/home/agentuity ./local
+agentuity cloud sandbox mkdir <sandboxId> /path/to/dir
+agentuity cloud sandbox rm <sandboxId> /path/to/file
+
+# Environment variables
+agentuity cloud sandbox env <sandboxId> VAR1=value1 VAR2=value2
+agentuity cloud sandbox env <sandboxId> --delete VAR1
+
+# Snapshots
+agentuity cloud sandbox snapshot create <sandboxId> \
+  [--name <name>] [--description <text>] [--tag <tag>]
+agentuity cloud sandbox snapshot list --json
+```
+
+**Snapshot tags:** Default to `latest`. Max 128 chars, must match `^[a-zA-Z0-9][a-zA-Z0-9._-]*$`.
+
+### Network & Public URLs
+
+| Scenario | Use `--network`? | Use `--port`? |
+|----------|------------------|---------------|
+| Running tests locally | No | No |
+| Installing npm packages | Yes | No |
+| Running web server for internal testing | Yes | No |
+| Exposing dev preview to share | Yes | Yes |
+| API that external services call | Yes | Yes |
+
+**Public URL format:** `https://s{identifier}.agentuity.run`
+
+### SSH (Remote Access)
+
+```bash
+# SSH into deployed projects
+agentuity cloud ssh                                         # Current project
+agentuity cloud ssh proj_abc123                             # Specific project
+agentuity cloud ssh proj_abc123 'tail -f /var/log/app.log'  # Run command
+
+# SSH into sandboxes
+agentuity cloud ssh sbx_abc123                              # Interactive shell
+
+# File transfer
+agentuity cloud scp upload ./config.json --identifier=proj_abc123
+agentuity cloud scp download /var/log/app.log --identifier=deploy_abc123
+```
+
+### Database (Postgres)
+
+```bash
+agentuity cloud db create <name> [--description "<text>"] --json
+agentuity cloud db list --json
+agentuity cloud db sql <name> "<query>" --json
+agentuity cloud db delete <name> --json
+```
+
+---
+
+## Deployment Commands
+
+```bash
+# Deploy current project
+agentuity deploy
+
+# Deploy with specific environment
+agentuity deploy --env production
+
+# List deployments
+agentuity cloud deployment list --json
+
+# Get deployment details
+agentuity cloud deployment get <deploymentId> --json
+```
+
+## Project Configuration
+
+### agentuity.json
+
+```json
+{
+  "projectId": "proj_abc123",
+  "orgId": "org_xyz",
+  "region": "use"
+}
+```
+
+### CLI Profile (~/.config/agentuity/production.yaml)
+
+Contains `orgId` from `preferences.orgId` — used as fallback when `agentuity.json` doesn't have orgId.
+
+## Common Mistakes
+
+| Mistake | Better Approach | Why |
+|---------|-----------------|-----|
+| Blindly adding `--region` flag | Check config first | Region may already be configured |
+| Using npm for Agentuity projects | Always use `bun` | Agentuity is Bun-native |
+| Hardcoding sandbox paths as `/app` | Use `/home/agentuity` | That's the default working directory |
+| Making up CLI flags | Run `--help` first | Flags change between versions |
+| Fabricating deployment URLs | Read actual output | URLs are generated dynamically |

package/src/install.ts

@@ -0,0 +1,150 @@
+/**
+ * @agentuity/claude-code - Agentuity Coder plugin for Claude Code
+ *
+ * Install script that configures the plugin for the current project.
+ * Sets up permissions for Agentuity Cloud CLI commands.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export interface InstallConfig {
+	projectId?: string;
+	orgId?: string;
+	region?: string;
+}
+
+interface ClaudeSettings {
+	permissions?: {
+		allow?: string[];
+		deny?: string[];
+		ask?: string[];
+	};
+	[key: string]: unknown;
+}
+
+const AGENTUITY_PERMISSIONS = [
+	"Bash(agentuity cloud *)",
+	"Bash(agentuity auth whoami *)",
+];
+
+const AGENTUITY_DENY_PERMISSIONS = [
+	"Bash(agentuity cloud secrets *)",
+	"Bash(agentuity cloud secret *)",
+	"Bash(agentuity cloud apikey *)",
+	"Bash(agentuity auth token *)",
+];
+
+/**
+ * Read agentuity.json from the current project if it exists.
+ */
+export async function readProjectConfig(): Promise<InstallConfig> {
+	try {
+		const file = Bun.file("agentuity.json");
+		if (await file.exists()) {
+			const config = await file.json();
+			return {
+				projectId: config.projectId,
+				orgId: config.orgId,
+				region: config.region,
+			};
+		}
+	} catch {
+		// No agentuity.json found or invalid
+	}
+	return {};
+}
+
+/**
+ * Read a Claude Code settings JSON file.
+ */
+async function readSettings(path: string): Promise<ClaudeSettings> {
+	try {
+		const file = Bun.file(path);
+		if (await file.exists()) {
+			return await file.json();
+		}
+	} catch {
+		// File doesn't exist or is invalid
+	}
+	return {};
+}
+
+/**
+ * Write a Claude Code settings JSON file.
+ */
+async function writeSettings(
+	path: string,
+	settings: ClaudeSettings,
+): Promise<void> {
+	await Bun.write(path, JSON.stringify(settings, null, 2) + "\n");
+}
+
+/**
+ * Ensure Agentuity Cloud permissions are configured in Claude Code settings.
+ * Adds allow rules for agentuity cloud commands and deny rules for sensitive ones.
+ */
+async function configurePermissions(): Promise<{ added: number }> {
+	const settingsPath = join(homedir(), ".claude", "settings.local.json");
+	const settings = await readSettings(settingsPath);
+
+	if (!settings.permissions) {
+		settings.permissions = {};
+	}
+	if (!settings.permissions.allow) {
+		settings.permissions.allow = [];
+	}
+	if (!settings.permissions.deny) {
+		settings.permissions.deny = [];
+	}
+
+	let added = 0;
+
+	for (const perm of AGENTUITY_PERMISSIONS) {
+		if (!settings.permissions.allow.includes(perm)) {
+			settings.permissions.allow.push(perm);
+			added++;
+		}
+	}
+
+	for (const perm of AGENTUITY_DENY_PERMISSIONS) {
+		if (!settings.permissions.deny.includes(perm)) {
+			settings.permissions.deny.push(perm);
+			added++;
+		}
+	}
+
+	if (added > 0) {
+		await writeSettings(settingsPath, settings);
+	}
+
+	return { added };
+}
+
+/**
+ * Install the Agentuity Coder plugin.
+ * This is called when the plugin is first installed.
+ */
+export async function install(): Promise<void> {
+	const config = await readProjectConfig();
+
+	// Configure Claude Code permissions for Agentuity Cloud commands
+	const { added } = await configurePermissions();
+	if (added > 0) {
+		console.log(
+			`Configured ${added} permission rules for Agentuity Cloud commands`,
+		);
+	}
+
+	if (config.projectId) {
+		console.log(
+			`Agentuity Coder configured for project: ${config.projectId}`,
+		);
+	} else {
+		console.log(
+			"Agentuity Coder installed (no agentuity.json found - will use session-start hook for context)",
+		);
+	}
+}
+
+export default install;