@standardagents/vue 0.1.0-dev.ffffff

package/LICENSE.txt

@@ -0,0 +1,48 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2025 FormKit Inc. All Rights Reserved.
+
+UNLICENSED - DO NOT USE
+
+This software and associated documentation files (the "Software") are the sole
+and exclusive property of FormKit Inc. ("FormKit").
+
+USE RESTRICTIONS
+
+The Software is UNLICENSED and proprietary. NO PERMISSION is granted to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, or to permit persons to whom the Software is furnished to do so,
+under any circumstances, without prior written authorization from FormKit Inc.
+
+UNAUTHORIZED USE PROHIBITED
+
+Any use of this Software without a valid, written license agreement signed by
+authorized officers of FormKit Inc. is strictly prohibited and constitutes
+unauthorized use and infringement of FormKit's intellectual property rights.
+
+LICENSING INQUIRIES
+
+Organizations interested in licensing this Software should contact:
+enterprise@formkit.com
+
+A written license agreement must be executed before any use of this Software
+is authorized.
+
+NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+FORMKIT INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+GOVERNING LAW
+
+This license shall be governed by and construed in accordance with the laws
+of the jurisdiction in which FormKit Inc. is incorporated, without regard to
+its conflict of law provisions.
+
+FormKit Inc.
+https://formkit.com
+enterprise@formkit.com

package/README.md

@@ -0,0 +1,379 @@
+# @standardagents/vue
+
+Vue 3 composables and components for Standard Agents - connect to AI agent threads with real-time updates, send messages, manage files, and listen for custom events.
+
+## Installation
+
+```bash
+npm install @standardagents/vue
+# or
+pnpm add @standardagents/vue
+# or
+yarn add @standardagents/vue
+```
+
+**Requirements:** Vue 3.3+
+
+## Quick Start
+
+```typescript
+// main.ts
+import { createApp } from 'vue'
+import { StandardAgentsPlugin } from '@standardagents/vue'
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(StandardAgentsPlugin, { endpoint: 'https://api.example.com' })
+app.mount('#app')
+```
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { ThreadProvider, useThread } from '@standardagents/vue'
+</script>
+
+<template>
+  <ThreadProvider threadId="thread-123">
+    <ChatInterface />
+  </ThreadProvider>
+</template>
+```
+
+```vue
+<!-- ChatInterface.vue -->
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useThread } from '@standardagents/vue'
+
+const { messages, sendMessage, status } = useThread()
+const input = ref('')
+
+const handleSend = async () => {
+  await sendMessage({ role: 'user', content: input.value })
+  input.value = ''
+}
+</script>
+
+<template>
+  <div>
+    <p>Status: {{ status }}</p>
+    <div v-for="msg in messages" :key="msg.id">
+      <strong>{{ msg.role }}:</strong> {{ msg.content }}
+    </div>
+    <input v-model="input" @keyup.enter="handleSend" />
+    <button @click="handleSend">Send</button>
+  </div>
+</template>
+```
+
+## Authentication
+
+The package reads the authentication token from `localStorage` using the key `agentbuilder_auth_token`:
+
+```typescript
+// Set the token before using the composables
+localStorage.setItem('agentbuilder_auth_token', 'your-token-here')
+```
+
+All API requests and WebSocket connections will automatically include this token.
+
+## API Reference
+
+### `StandardAgentsPlugin`
+
+Vue plugin that configures the Standard Agents client for all components.
+
+**Options:**
+
+- `endpoint: string` - The API endpoint URL (required)
+
+```typescript
+import { createApp } from 'vue'
+import { StandardAgentsPlugin } from '@standardagents/vue'
+
+const app = createApp(App)
+app.use(StandardAgentsPlugin, { endpoint: 'https://api.example.com' })
+```
+
+---
+
+### `ThreadProvider`
+
+Component that establishes a WebSocket connection to a specific thread and provides context to child components.
+
+**Props:**
+
+- `threadId: string` - The thread ID to connect to
+- `preload?: boolean` - Fetch existing messages on mount (default: `true`)
+- `live?: boolean` - Enable WebSocket for real-time updates (default: `true`)
+- `useWorkblocks?: boolean` - Group tool calls into workblocks (default: `false`)
+- `depth?: number` - Message depth level (default: `0`)
+- `includeSilent?: boolean` - Include silent messages (default: `false`)
+- `endpoint?: string` - Override the endpoint from plugin config
+
+```vue
+<template>
+  <ThreadProvider threadId="thread-123" :live="true">
+    <YourComponents />
+  </ThreadProvider>
+</template>
+
+<script setup lang="ts">
+import { ThreadProvider } from '@standardagents/vue'
+</script>
+```
+
+---
+
+### `useThread()`
+
+Composable to access the full thread context. Must be used within a `ThreadProvider`.
+
+**Returns:**
+
+- `threadId: string` - The thread ID
+- `messages: Ref<Message[]>` - Reactive array of messages
+- `workblocks: ComputedRef<ThreadMessage[]>` - Messages transformed to workblocks (if `useWorkblocks` is true)
+- `status: Ref<ConnectionStatus>` - Connection status (`"connecting"` | `"connected"` | `"disconnected"` | `"reconnecting"`)
+- `loading: Ref<boolean>` - Loading state (alias: `isLoading`)
+- `error: Ref<Error | null>` - Error state
+- `options: ThreadProviderOptions` - Options passed to the provider
+- `sendMessage: (payload: SendMessagePayload) => Promise<Message>` - Send a message
+- `stopExecution: () => Promise<void>` - Stop current execution
+- `onEvent: <T>(eventType, callback) => () => void` - Subscribe to custom events (alias: `subscribeToEvent`)
+- `files: ComputedRef<ThreadFile[]>` - All files (pending + committed)
+- `addFiles: (files: File[] | FileList) => void` - Upload files
+- `removeFile: (id: string) => void` - Remove a pending file
+- `getFileUrl: (file: ThreadFile) => string` - Get file URL
+- `getThumbnailUrl: (file: ThreadFile) => string` - Get thumbnail URL
+- `getPreviewUrl: (file: ThreadFile) => string | null` - Get preview URL
+
+**Example:**
+
+```vue
+<script setup lang="ts">
+import { useThread } from '@standardagents/vue'
+
+const {
+  messages,
+  sendMessage,
+  stopExecution,
+  status,
+  isLoading,
+  files,
+  addFiles,
+  onEvent,
+} = useThread()
+
+// Subscribe to custom events
+onEvent<{ todos: string[] }>('todo-updated', (data) => {
+  console.log('Todos:', data.todos)
+})
+</script>
+
+<template>
+  <div>
+    <p v-if="isLoading">Loading...</p>
+    <p>Status: {{ status }}</p>
+
+    <div v-for="msg in messages" :key="msg.id">
+      <strong>{{ msg.role }}:</strong> {{ msg.content }}
+    </div>
+
+    <input type="file" multiple @change="(e) => addFiles(e.target.files)" />
+
+    <div v-for="file in files" :key="file.id">
+      {{ file.name }} ({{ file.status }})
+    </div>
+
+    <button @click="sendMessage({ role: 'user', content: 'Hello!' })">Send</button>
+    <button @click="stopExecution">Stop</button>
+  </div>
+</template>
+```
+
+---
+
+## File Management
+
+The `useThread()` composable provides file management capabilities:
+
+```vue
+<script setup lang="ts">
+import { useThread } from '@standardagents/vue'
+
+const { files, addFiles, removeFile, getPreviewUrl } = useThread()
+
+const handleFileChange = (event: Event) => {
+  const input = event.target as HTMLInputElement
+  if (input.files) {
+    addFiles(input.files)
+  }
+}
+</script>
+
+<template>
+  <div>
+    <input type="file" multiple accept="image/*,.pdf,.txt" @change="handleFileChange" />
+
+    <div v-for="file in files" :key="file.id">
+      <img
+        v-if="file.isImage && file.status !== 'uploading'"
+        :src="getPreviewUrl(file) || ''"
+        :alt="file.name"
+        width="50"
+      />
+      <span>{{ file.name }}</span>
+      <span>{{ file.status }}</span>
+      <span v-if="file.status === 'uploading'">Uploading...</span>
+      <span v-if="file.status === 'error'">Error: {{ file.error }}</span>
+      <button v-if="file.status !== 'committed'" @click="removeFile(file.id)">
+        Remove
+      </button>
+    </div>
+  </div>
+</template>
+```
+
+### File States
+
+- `uploading` - File is being uploaded
+- `ready` - Upload complete, file ready to attach to message
+- `committed` - File is attached to a sent message
+- `error` - Upload failed
+
+---
+
+## Types
+
+```typescript
+interface Message {
+  id: string
+  role: 'user' | 'assistant' | 'system' | 'tool'
+  content: string | null
+  created_at: number
+  attachments?: string // JSON array of AttachmentRef
+}
+
+interface SendMessagePayload {
+  role: 'user' | 'assistant' | 'system'
+  content: string
+  silent?: boolean
+  attachments?: string[]  // Paths of files to attach
+}
+
+interface ThreadFile {
+  id: string
+  name: string
+  mimeType: string
+  size: number
+  isImage: boolean
+  status: 'uploading' | 'ready' | 'committed' | 'error'
+  error?: string
+  path?: string
+  localPreviewUrl: string | null
+}
+
+type ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'reconnecting'
+```
+
+---
+
+## Complete Example
+
+```vue
+<script setup lang="ts">
+import { onMounted } from 'vue'
+import { ThreadProvider } from '@standardagents/vue'
+
+onMounted(() => {
+  localStorage.setItem('agentbuilder_auth_token', 'your-token')
+})
+</script>
+
+<template>
+  <ThreadProvider threadId="thread-123">
+    <AgentChat />
+  </ThreadProvider>
+</template>
+```
+
+```vue
+<!-- AgentChat.vue -->
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useThread } from '@standardagents/vue'
+
+const input = ref('')
+
+const {
+  messages,
+  sendMessage,
+  stopExecution,
+  status,
+  isLoading,
+  files,
+  addFiles,
+  removeFile,
+  getPreviewUrl,
+} = useThread()
+
+const handleSend = async () => {
+  if (!input.value.trim()) return
+  await sendMessage({ role: 'user', content: input.value })
+  input.value = ''
+}
+
+const handleFileChange = (event: Event) => {
+  const target = event.target as HTMLInputElement
+  if (target.files) addFiles(target.files)
+}
+</script>
+
+<template>
+  <div>
+    <p v-if="isLoading">Loading messages...</p>
+
+    <div v-for="msg in messages" :key="msg.id">
+      <strong>{{ msg.role }}:</strong> {{ msg.content }}
+    </div>
+
+    <input type="file" multiple @change="handleFileChange" />
+
+    <div v-for="file in files.filter(f => f.status !== 'committed')" :key="file.id">
+      <img
+        v-if="file.isImage && getPreviewUrl(file)"
+        :src="getPreviewUrl(file)!"
+        :alt="file.name"
+        width="50"
+      />
+      <span>{{ file.name }} ({{ file.status }})</span>
+      <button @click="removeFile(file.id)">x</button>
+    </div>
+
+    <div>
+      <input v-model="input" @keyup.enter="handleSend" />
+      <button @click="handleSend">Send</button>
+      <button @click="stopExecution">Stop</button>
+      <span>Status: {{ status }}</span>
+    </div>
+  </div>
+</template>
+```
+
+---
+
+## TypeScript Support
+
+The package includes full TypeScript definitions:
+
+```typescript
+import type {
+  Message,
+  SendMessagePayload,
+  ThreadFile,
+  ConnectionStatus,
+  ThreadContext,
+} from '@standardagents/vue'
+```