@runtypelabs/timely-a2a 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Runtype Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,404 @@
+# Timely (@runtypelabs/timely-a2a)
+
+Time-focused A2A agent with **deterministic time tools** and LLM-powered time chat.
+
+## What is Timely?
+
+LLMs can't reliably:
+
+- Tell you what day "next Tuesday" is
+- Calculate dates ("30 days from now")
+- Convert timezones correctly
+- Know what time it is
+
+Timely is an A2A agent that solves this with deterministic time skills that compute answers from the system clock — no generation, no hallucination. The `chat` skill is restricted to time, date, timezone, and scheduling questions, using tool-calling to invoke the deterministic time tools. Other agents can call these tools via A2A to get reliable temporal data.
+
+## Quick Start
+
+### Run an A2A Server (Echo Mode - for testing)
+
+```bash
+# Using CLI
+npx @runtypelabs/timely-a2a serve --echo
+```
+
+This starts a server at:
+
+- Agent Card: `http://localhost:9999/.well-known/agent-card.json`
+- A2A Endpoint: `http://localhost:9999/a2a`
+
+### Test a time skill
+
+```bash
+curl -X POST http://localhost:9999/a2a \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "message/send",
+    "params": {
+      "message": {
+        "role": "user",
+        "parts": [{"data": {"date": "2025-02-04"}}]
+      },
+      "metadata": { "skill": "time/day_of_week" }
+    }
+  }'
+```
+
+Returns:
+```bash
+{ "result": { "day": "Tuesday", ... }, "computed": { "method": "deterministic" } }
+```
+
+### Run with LLM
+
+Uses [Vercel AI Gateway](https://sdk.vercel.ai/docs/ai-sdk-core/gateway) to access any model provider through a single API key.
+
+```bash
+# Vercel AI Gateway (recommended — supports any provider)
+AI_GATEWAY_API_KEY=xxx npx @runtypelabs/timely-a2a serve
+```
+
+The default model is `alibaba/qwen3.5-flash`. Use `--model` to switch:
+
+```bash
+AI_GATEWAY_API_KEY=xxx npx @runtypelabs/timely-a2a serve --model openai/gpt-4o-mini
+```
+
+<details>
+<summary>Direct provider fallback (without AI Gateway)</summary>
+
+```bash
+# OpenAI
+OPENAI_API_KEY=sk-xxx npx @runtypelabs/timely-a2a serve --model gpt-4o-mini --provider openai
+
+# Anthropic
+ANTHROPIC_API_KEY=sk-xxx npx @runtypelabs/timely-a2a serve --model claude-sonnet-4-6 --provider anthropic
+```
+
+Direct provider mode only supports `openai` and `anthropic` providers, and the model name must not contain a `/` prefix.
+
+</details>
+
+### Test an A2A Endpoint
+
+The server must be running first. Use two terminals:
+
+**Terminal 1** — start the server:
+
+```bash
+# Echo mode (no API key needed)
+npx @runtypelabs/timely-a2a serve --echo
+```
+
+```bash
+# Or with LLM (requires AI_GATEWAY_API_KEY)
+AI_GATEWAY_API_KEY=xxx npx @runtypelabs/timely-a2a serve
+```
+
+**Terminal 2** — run the test:
+
+```bash
+# Test echo (works with echo mode)
+npx @runtypelabs/timely-a2a test http://localhost:9999
+
+# Test with streaming (chat requires LLM mode + API key)
+npx @runtypelabs/timely-a2a test http://localhost:9999 --stream --skill chat --message "What time is it in Tokyo?"
+```
+
+> Run `npx @runtypelabs/timely-a2a --help` to see all commands and options.
+
+### Test Runtype A2A Surface
+
+```bash
+npx @runtypelabs/timely-a2a test-runtype \
+  --product-id prod_xxx \
+  --surface-id surf_xxx \
+  --api-key a2a_xxx \
+  --environment local \
+  --message "Hello!"
+```
+
+## Available Skills
+
+### Time Tools (Deterministic)
+
+| Skill                | Description                           |
+| -------------------- | ------------------------------------- |
+| `time/now`           | Current time with timezone            |
+| `time/parse`         | Parse "next Tuesday 3pm" to timestamp |
+| `time/convert`       | Convert between timezones             |
+| `time/add`           | Add days/weeks/months to a date       |
+| `time/diff`          | Duration between two dates            |
+| `time/day_of_week`   | What day is this date?                |
+| `time/is_past`       | Is this timestamp in the past?        |
+| `time/business_days` | Add/subtract business days            |
+
+### Time Chat (LLM-Powered)
+
+| Skill  | Description                                                             |
+| ------ | ----------------------------------------------------------------------- |
+| `chat` | Conversational assistant for time, date, timezone, and scheduling questions |
+| `echo` | Echo input (testing)                                                    |
+
+`chat` can invoke skills tagged with `tool` (for example the deterministic `time/*` skills) through AI SDK tool calling. It is restricted to time-related queries and will politely decline off-topic questions.
+
+Time tools return structured responses with a `computed.method: "deterministic"` field and `usage: "Use this value directly. Do not recalculate."` guidance for calling agents.
+
+Example prompt that triggers tool use from `chat`:
+
+```bash
+npx @runtypelabs/timely-a2a test http://localhost:9999 \
+  --skill chat \
+  --message "What day of the week is 2026-02-09 in UTC?"
+```
+
+## Connecting to Runtype
+
+### As an External Agent
+
+1. Start the A2A server:
+
+   ```bash
+   npx @runtypelabs/timely-a2a serve --echo --port 9999
+   ```
+
+2. In Runtype Dashboard:
+   - Go to your Product
+   - Click "Add Capability" > "Connect External"
+   - Enter:
+     - Agent Card URL: `http://localhost:9999/.well-known/agent-card.json`
+     - A2A Endpoint URL: `http://localhost:9999/a2a`
+   - Click "Connect & Add"
+
+### Testing Runtype's A2A Surface
+
+1. Create an A2A Surface in Runtype Dashboard
+2. Add capabilities (flows) to the surface
+3. Generate an API key for the surface
+4. Test with the CLI:
+   ```bash
+   npx @runtypelabs/timely-a2a test-runtype \
+     --product-id prod_xxx \
+     --surface-id surf_xxx \
+     --api-key a2a_xxx \
+     --environment local
+   ```
+
+## Programmatic Usage
+
+### Create a Server
+
+```typescript
+import { createA2AServer } from '@runtypelabs/timely-a2a'
+
+// Requires AI_GATEWAY_API_KEY env var for gateway models (provider/model format)
+const server = createA2AServer({
+  config: {
+    name: 'Timely',
+    description: 'Time-focused A2A agent with deterministic time tools and LLM-powered time chat',
+    port: 9999,
+  },
+  llmConfig: {
+    provider: 'openai',
+    model: 'alibaba/qwen3.5-flash', // gateway model — any provider via Vercel AI Gateway
+    temperature: 0.7,
+  },
+})
+
+await server.start()
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  await server.stop()
+})
+```
+
+### Create a Client
+
+```typescript
+import { A2AClient } from '@runtypelabs/timely-a2a'
+
+const client = new A2AClient({
+  baseUrl: 'http://localhost:9999',
+})
+
+// Get agent card
+const agentCard = await client.getAgentCard()
+console.log(
+  'Skills:',
+  agentCard.skills.map((s) => s.name)
+)
+
+// Send a task
+const task = await client.sendTask({
+  skill: 'chat',
+  message: {
+    role: 'user',
+    parts: [{ type: 'text', text: 'What time is it in Tokyo?' }],
+  },
+})
+
+console.log('Response:', task.artifacts?.[0]?.parts?.[0]?.text)
+```
+
+### Test Runtype Surface
+
+```typescript
+import { createRuntypeA2AClient } from '@runtypelabs/timely-a2a'
+
+const client = createRuntypeA2AClient({
+  productId: 'prod_xxx',
+  surfaceId: 'surf_xxx',
+  apiKey: 'a2a_xxx',
+  environment: 'local', // or 'staging', 'production'
+})
+
+// Send streaming task
+await client.sendTaskStreaming(
+  {
+    skill: 'my-capability',
+    message: {
+      role: 'user',
+      parts: [{ type: 'text', text: 'What time is it in London?' }],
+    },
+  },
+  {
+    onChunk: (text) => process.stdout.write(text),
+    onStatus: (status) => console.log('Status:', status),
+  }
+)
+```
+
+## CLI Reference
+
+Run `npx @runtypelabs/timely-a2a --help` for all commands and options.
+
+### `serve` - Start A2A Server
+
+```
+Usage: timely-a2a serve [options]
+
+Options:
+  -p, --port <port>          Port to listen on (default: "9999")
+  -h, --host <host>          Host to bind to (default: "localhost")
+  -n, --name <name>          Agent name (default: "Timely")
+  --echo                     Run in echo mode (no LLM, for testing)
+  --provider <provider>      LLM provider: openai, anthropic (default: "openai")
+  --model <model>            LLM model (default: "alibaba/qwen3.5-flash")
+  --temperature <temp>       LLM temperature (default: "0.7")
+```
+
+### `test` - Test A2A Endpoint
+
+```
+Usage: timely-a2a test [options] <url>
+
+Arguments:
+  url                   Base URL of the A2A endpoint
+
+Options:
+  -s, --skill <skill>   Skill to test (default: "echo")
+  -m, --message <msg>   Message to send (default: "Hello from A2A client!")
+  --stream              Use streaming mode
+  -k, --api-key <key>   API key for authentication
+```
+
+### `test-runtype` - Test Runtype A2A Surface
+
+```
+Usage: timely-a2a test-runtype [options]
+
+Options:
+  --product-id <id>     Runtype product ID (required)
+  --surface-id <id>     Runtype surface ID (required)
+  --api-key <key>       A2A API key (required)
+  -e, --environment     Environment: production, staging, local (default: "local")
+  -s, --skill <skill>   Skill/capability to test
+  -m, --message <msg>   Message to send (default: "Hello from A2A client!")
+  --stream              Use streaming mode
+```
+
+## A2A Protocol
+
+This package implements [A2A Protocol v0.3](https://a2a-protocol.org/v0.3.0/specification/).
+
+### Endpoints
+
+- `GET /.well-known/agent-card.json` - Agent Card discovery (also serves `/.well-known/agent.json` for backward compat)
+- `POST /a2a` - JSON-RPC endpoint
+
+### Supported Methods
+
+| Spec Method (preferred) | Legacy Alias | Description |
+| --- | --- | --- |
+| `message/send` | `tasks/send`, `SendMessage` | Send a message (synchronous) |
+| `message/stream` | `tasks/sendSubscribe`, `SendStreamingMessage` | Send a message with SSE streaming |
+| `GetTask` | `tasks/get` | Get task status |
+| `CancelTask` | `tasks/cancel` | Cancel a running task |
+| `ping` | | Health check |
+
+## Vercel Deployment
+
+Deploy your A2A agent to Vercel for serverless operation.
+
+### Option 1: Deploy the `vercel-app` directory
+
+1. In Vercel dashboard, set **Root Directory** to `vercel-app`
+2. Add environment variables:
+   - `AI_GATEWAY_API_KEY` — Vercel AI Gateway key (recommended)
+   - `AGENT_NAME` (optional)
+   - `ECHO_MODE=true` for testing without LLM
+   - Or use direct provider keys as fallback: `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`
+3. Deploy
+
+### Option 2: Add to Existing Next.js App
+
+Install the package and use the Vercel handlers. Set `AI_GATEWAY_API_KEY` in your environment for gateway models:
+
+```typescript
+// app/api/a2a/route.ts
+import { createA2AHandler } from '@runtypelabs/timely-a2a/vercel'
+
+export const POST = createA2AHandler({
+  name: 'Timely',
+  llmConfig: { provider: 'openai', model: 'alibaba/qwen3.5-flash' },
+})
+
+// app/.well-known/agent-card.json/route.ts
+import { createAgentCardHandler } from '@runtypelabs/timely-a2a/vercel'
+
+export const GET = createAgentCardHandler({
+  name: 'Timely',
+  llmConfig: { provider: 'openai', model: 'alibaba/qwen3.5-flash' },
+})
+```
+
+### Serverless Limitations
+
+Since Vercel functions are stateless:
+
+- `GetTask` returns "not available" (no task storage)
+- `CancelTask` returns "not available" (can't cancel in-flight tasks)
+- Use `message/stream` for streaming responses
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Development mode (watch)
+pnpm dev
+
+# Type check
+pnpm typecheck
+
+# Clean
+pnpm clean
+```
+
+## License
+
+MIT