@towns-labs/app-framework 4.0.0

package/README.md

@@ -0,0 +1,147 @@
+# @towns-labs/app-framework
+
+An agent framework for Towns.
+
+## Installing
+
+We suggest users to quickstart a project using our cli.
+
+```bash
+$ bunx towns-agent init
+```
+
+If you prefer to install manually:
+
+```bash
+$ bun add @towns-labs/app-framework viem hono
+```
+
+## Usage
+
+With Node:
+
+```ts
+import { makeTownsApp } from "@towns-labs/app-framework";
+import { serve } from "@hono/node-server";
+
+const app = new Hono();
+const agent = await makeTownsApp("<app-private-data-base64>");
+
+agent.onMessage((handler, { channelId, isMentioned }) => {
+  if (isMentioned) {
+    handler.sendMessage(channelId, "Hello, world!");
+  }
+});
+
+const { jwtMiddleware, handler } = agent.start();
+app.post("/webhook", jwtMiddleware, handler);
+
+serve({ fetch: app.fetch });
+```
+
+With Bun:
+
+```ts
+import { makeTownsApp } from "@towns-labs/app-framework";
+
+const app = new Hono();
+const agent = await makeTownsApp("<app-private-data-base64>");
+
+agent.onMessage((handler, { channelId, isMentioned }) => {
+  if (isMentioned) {
+    handler.sendMessage(channelId, "Hello, world!");
+  }
+});
+
+const { jwtMiddleware, handler } = agent.start();
+app.post("/webhook", jwtMiddleware, handler);
+
+export default app;
+```
+
+## Identity Metadata (ERC-8004)
+
+Agents can optionally define ERC-8004 compliant identity metadata for agent discovery and trust.
+
+### Minimal Example
+
+Create `identity.ts`:
+
+```ts
+import type { AgentAgentIdentityConfig } from "@towns-labs/app-framework";
+
+const identity = {
+  name: "My Agent",
+  description: "A helpful agent for Towns",
+  image: "https://example.com/agent-logo.png",
+  domain: "myAgent.example.com",
+} as const satisfies AgentIdentityConfig;
+
+export default identity;
+```
+
+Use in agent setup:
+
+```ts
+import identity from "./identity";
+
+const agent = await makeTownsApp(process.env.APP_PRIVATE_DATA!, {
+  commands,
+  identity,
+});
+
+// Get metadata for hosting at /.well-known/agent-metadata.json
+const metadata = agent.getIdentityMetadata();
+app.get("/.well-known/agent-metadata.json", metadata);
+```
+
+### Advanced Example
+
+For full ERC-8004 compliance with endpoints and trust models:
+
+```ts
+import type { AgentIdentityConfig } from "@towns-labs/app-framework";
+
+const identity = {
+  name: "Advanced Agent",
+  description: "AI-powered agent with multi-protocol support",
+  image: "https://example.com/agent-logo.png",
+  motto: "Building the future of agent economies",
+  domain: "agent.example.com",
+
+  endpoints: [
+    {
+      name: "A2A",
+      endpoint: "https://agent.example.com/.well-known/agent-card.json",
+      version: "0.3.0",
+    },
+    {
+      name: "MCP",
+      endpoint: "https://mcp.agent.example.com/",
+      version: "2025-06-18",
+    },
+  ],
+
+  registrations: [],
+
+  supportedTrust: ["reputation", "crypto-economic"],
+
+  attributes: [
+    { trait_type: "Category", value: "Gateway" },
+    { trait_type: "Model", value: "GPT-4" },
+  ],
+} as const satisfies AgentIdentityConfig;
+
+export default identity;
+```
+
+The agent automatically adds `agentWallet` endpoint using the agent's app address and `A2A` endpoint if domain is configured.
+
+## Debug Logging
+
+Agent framework uses `debug` package for logging.
+You can enable by setting the `DEBUG` environment variable to `csb:agent`.
+
+```bash
+DEBUG=csb:agent node dist/agent.cjs
+```