@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/cloud/artifact.ts

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import type { AgentBuildResult, AgentManifestWithBundle } from "../runtime/targets/cloudflare/build";
+import { AgentKitError } from "../runtime/errors";
+import type { HostedDeployArtifact } from "./contracts";
+
+export async function createHostedDeployArtifact(build: AgentBuildResult): Promise<HostedDeployArtifact> {
+  const [manifestSource, workerSource, wranglerSource] = await Promise.all([
+    readFile(build.manifestPath, "utf8"),
+    readFile(build.workerPath, "utf8"),
+    readFile(build.wranglerPath, "utf8"),
+  ]);
+  const manifest = JSON.parse(manifestSource) as AgentManifestWithBundle;
+  const workerSha256 = sha256(workerSource);
+
+  if (workerSha256 !== build.bundleSha256 || workerSha256 !== manifest.bundle.sha256) {
+    throw new AgentKitError("artifact_integrity_error", "Worker SHA-256 does not match the build manifest.");
+  }
+
+  const artifact: HostedDeployArtifact = {
+    manifest,
+    worker: {
+      content_type: "application/javascript",
+      source: workerSource,
+      sha256: workerSha256,
+    },
+    wrangler: {
+      content_type: "application/json",
+      source: wranglerSource,
+    },
+  };
+
+  if (build.tursoSchemaPath) {
+    const source = await readFile(build.tursoSchemaPath, "utf8");
+    artifact.turso_schema = {
+      content_type: "text/sql",
+      source,
+      sha256: sha256(source),
+    };
+  }
+
+  return artifact;
+}
+
+function sha256(source: string): string {
+  return createHash("sha256").update(source).digest("hex");
+}

package/src/cloud/client.ts

@@ -0,0 +1,79 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { AgentBuildResult } from "../runtime/targets/cloudflare/build";
+import type { LocalDeployState } from "../runtime/core/deploy-state";
+import { AgentKitError } from "../runtime/errors";
+import { createHostedDeployArtifact } from "./artifact";
+import type { AgentKitCloudDeployOptions, CreateDeployRequest, CreateDeployResponse } from "./contracts";
+
+export async function deployBuildToAgentKitCloud(
+  build: AgentBuildResult,
+  options: AgentKitCloudDeployOptions,
+): Promise<CreateDeployResponse> {
+  const artifact = await createHostedDeployArtifact(build);
+  const headers = new Headers({
+    "Content-Type": "application/json",
+  });
+  const apiToken = options.apiToken ?? process.env.AGENTKIT_CLOUD_API_TOKEN;
+
+  if (apiToken) {
+    headers.set("Authorization", `Bearer ${apiToken}`);
+  }
+
+  const response = await fetch(new URL("/v1/deploys", normalizeApiUrl(options.apiUrl)), {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      project_name: artifact.manifest.name,
+      anonymous: options.anonymous ?? !apiToken,
+      artifact,
+    } satisfies CreateDeployRequest),
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    const code =
+      payload && typeof payload === "object" && "error" in payload
+        ? String((payload as { error?: { code?: unknown } }).error?.code ?? "cloud_deploy_failed")
+        : "cloud_deploy_failed";
+    const message =
+      payload && typeof payload === "object" && "error" in payload
+        ? String((payload as { error?: { message?: unknown } }).error?.message ?? "AgentKit Cloud deploy failed.")
+        : `AgentKit Cloud deploy failed with HTTP ${response.status}.`;
+    throw new AgentKitError(code, message);
+  }
+
+  return payload as CreateDeployResponse;
+}
+
+export async function writeLocalDeployState(root: string, deploy: CreateDeployResponse): Promise<string> {
+  const statePath = join(root, ".agentkit/deploy.json");
+  const state: LocalDeployState = {
+    project_id: deploy.project.id,
+    deploy_id: deploy.deploy.id,
+    url: deploy.deploy.url,
+    target: "cloudflare",
+    runtime: "edge",
+    resources: {
+      cloudflare: {
+        worker_url: deploy.deploy.url,
+        durable_object_class: "AgentKitConversationStore",
+      },
+    },
+    owner_state: deploy.project.owner_state,
+    access: {
+      mode: deploy.deploy.access.mode,
+      private_token: deploy.deploy.access.private_token ?? undefined,
+    },
+    created_at: new Date().toISOString(),
+  };
+
+  await mkdir(join(root, ".agentkit"), { recursive: true });
+  await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  return statePath;
+}
+
+function normalizeApiUrl(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}

package/src/cloud/contracts.ts

@@ -0,0 +1,47 @@
+import type { AgentManifestWithBundle } from "../runtime/targets/cloudflare/build";
+
+export type HostedDeployArtifact = {
+  manifest: AgentManifestWithBundle;
+  worker: {
+    content_type: "application/javascript";
+    source: string;
+    sha256: string;
+  };
+  wrangler: {
+    content_type: "application/json";
+    source: string;
+  };
+  turso_schema?: {
+    content_type: "text/sql";
+    source: string;
+    sha256: string;
+  };
+};
+
+export type CreateDeployRequest = {
+  project_name: string;
+  anonymous: boolean;
+  artifact: HostedDeployArtifact;
+};
+
+export type CreateDeployResponse = {
+  project: {
+    id: string;
+    owner_state: "anonymous" | "claimed";
+  };
+  deploy: {
+    id: string;
+    status: "ready" | "failed";
+    url: string;
+    access: {
+      mode: string;
+      private_token?: string;
+    };
+  };
+};
+
+export type AgentKitCloudDeployOptions = {
+  apiUrl: string;
+  apiToken?: string;
+  anonymous?: boolean;
+};

package/src/cloud/index.ts

@@ -0,0 +1,3 @@
+export * from "./artifact";
+export * from "./client";
+export * from "./contracts";

package/src/index.ts

@@ -244,7 +244,7 @@ export { runToolFromCwd } from "./runtime/tool-runner";
 export { startAgentDevServer } from "./runtime/dev-server";
 export { inspectAgentCapsule } from "./runtime/inspect";
 export { buildAgentCapsule } from "./runtime/build";
-export { deployBuildToAgentKitCloud, startAgentKitCloudServer } from "./runtime/deploy";
+export { deployBuildToAgentKitCloud } from "./runtime/deploy";
 export { AgentKitError } from "./runtime/errors";
 export type {
   ChannelAdapter,

package/src/providers/test.ts

@@ -37,6 +37,17 @@ export const testProviderAdapter: ProviderAdapter = {
       };
     }
 
+    const rememberedName = answerRememberedName(input.messages);
+
+    if (rememberedName) {
+      return {
+        message: {
+          role: "assistant",
+          content: rememberedName,
+        },
+      };
+    }
+
     return {
       message: {
         role: "assistant",
@@ -58,6 +69,46 @@ function findLastUserMessage(messages: AgentMessage[]): AgentMessage | undefined
   return undefined;
 }
 
+function answerRememberedName(messages: AgentMessage[]): string | null {
+  const lastUserMessage = findLastUserMessage(messages);
+
+  if (!lastUserMessage || !asksForName(lastUserMessage.content)) {
+    return null;
+  }
+
+  for (let index = messages.length - 2; index >= 0; index -= 1) {
+    const message = messages[index];
+
+    if (message.role !== "user") {
+      continue;
+    }
+
+    const name = extractName(message.content);
+
+    if (name) {
+      return /meu nome|qual\s+(é|e)\s*meu nome|como\s+(é|e)\s*meu nome/i.test(lastUserMessage.content)
+        ? `Seu nome é ${name}.`
+        : `Your name is ${name}.`;
+    }
+  }
+
+  return null;
+}
+
+function asksForName(content: string): boolean {
+  return /what(?:'s| is) my name\??/i.test(content) || /(como|qual)\s+(é|e)\s*(o\s+)?meu nome\??/i.test(content);
+}
+
+function extractName(content: string): string | null {
+  const match = content.match(/\bmy name is\s+(.+)$/i) ?? content.match(/\bmeu nome (?:é|e)\s+(.+)$/i);
+
+  if (!match) {
+    return null;
+  }
+
+  return match[1].trim().replace(/[.!?]+$/g, "") || null;
+}
+
 function parseToolRequest(content: string): { name: string; input?: unknown } | null {
   let parsed: unknown;
 

package/src/runtime/chat.ts

@@ -1,7 +1,7 @@
 import { getProviderAdapter } from "../providers";
 import type { AgentMessage, ProviderRunResult } from "../providers";
 import type { ToolRuntimeContext } from "../index";
-import type { PersistedChatRun } from "../storage/sqlite";
+import type { ConversationRecord, ConversationSummary, PersistedChatRun } from "../storage/sqlite";
 import type { LoadedAgentCapsule } from "./config";
 import { loadAgentCapsule } from "./config";
 import { openPreparedCapsuleStore } from "./database";
@@ -11,6 +11,7 @@ import { createToolRuntime } from "./tools";
 
 export type RunAgentMessageOptions = {
   message: string;
+  conversationId?: string;
   signal?: AbortSignal;
   runtime?: Partial<ToolRuntimeContext>;
 };
@@ -36,12 +37,14 @@ export async function runAgentMessage(
 
   const adapter = getProviderAdapter(capsule.config.provider);
   const env = await loadCapsuleEnv(capsule.root);
-  const messages: AgentMessage[] = [{ role: "user", content }];
   const { store } = await openPreparedCapsuleStore(capsule);
-  const conversation = store.createConversation({
+  const conversationId = normalizeConversationId(options.conversationId);
+  const { conversation, previousMessages } = resolveConversation(store, {
     agentName: capsule.config.name,
-    title: titleFromMessage(content),
+    conversationId,
+    firstMessage: content,
   });
+  const messages: AgentMessage[] = [...previousMessages, { role: "user", content }];
   const userMessage = store.appendMessage({
     conversationId: conversation.id,
     role: "user",
@@ -116,6 +119,58 @@ export async function runAgentMessage(
   }
 }
 
+function resolveConversation(
+  store: Awaited<ReturnType<typeof openPreparedCapsuleStore>>["store"],
+  input: {
+    agentName: string;
+    conversationId?: string;
+    firstMessage: string;
+  },
+): { conversation: ConversationSummary; previousMessages: AgentMessage[] } {
+  if (input.conversationId) {
+    const existing = store.getConversation(input.conversationId);
+
+    if (existing) {
+      return {
+        conversation: existing,
+        previousMessages: toProviderMessages(existing),
+      };
+    }
+  }
+
+  const conversation = store.createConversation({
+    id: input.conversationId,
+    agentName: input.agentName,
+    title: titleFromMessage(input.firstMessage),
+  });
+
+  return {
+    conversation,
+    previousMessages: [],
+  };
+}
+
+function toProviderMessages(conversation: ConversationRecord): AgentMessage[] {
+  return conversation.messages.map((message) => ({
+    role: message.role,
+    content: message.content,
+  }));
+}
+
+function normalizeConversationId(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const conversationId = value.trim();
+
+  if (!conversationId) {
+    throw new AgentKitError("validation_error", "conversationId must be a non-empty string when provided.");
+  }
+
+  return conversationId;
+}
+
 function withToolVisibilityInstructions(instructions: string, tools: LoadedAgentCapsule["config"]["tools"] = []): string {
   const internalTools = tools.filter((tool) => tool.visibility === "internal").map((tool) => tool.name).sort();
 

package/src/runtime/deploy.ts

@@ -1 +1 @@
-export * from "./targets/cloudflare/deploy";
+export * from "../cloud";

package/src/runtime/dev-server.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { createServer as createHttpServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { createServer as createNetServer } from "node:net";
@@ -21,12 +22,18 @@ import { runToolFromCwd } from "./tool-runner";
 export type AgentDevServerOptions = {
   port?: number;
   hostname?: string;
+  basePort?: number;
 };
 
 export type AgentDevServer = {
   capsule: LoadedAgentCapsule;
   hostname: string;
+  requestedPort: number | null;
   port: number;
+  portConflict: {
+    port: number;
+    agent?: string;
+  } | null;
   urls: {
     chat: string;
     api: string;
@@ -46,34 +53,83 @@ export async function startAgentDevServer(
 ): Promise<AgentDevServer> {
   const capsule = await loadAgentCapsule(cwd);
   const hostname = options.hostname ?? DEFAULT_HOSTNAME;
-  const port = options.port === 0 ? await findAvailablePort() : options.port ?? DEFAULT_PORT;
-  const channelDedupeKeys = new Set<string>();
-  const server = createHttpServer((incoming, outgoing) => {
-    void handleNodeRequest(capsule, incoming, outgoing, channelDedupeKeys);
-  });
-  const actualPort = await listen(server, hostname, port);
+  const requestedPort = options.port ?? options.basePort ?? DEFAULT_PORT;
+  const autoPort = options.port === undefined;
+  const start = await listenForDevServer(capsule, hostname, requestedPort, autoPort);
 
-  if (actualPort === undefined) {
+  if (start.actualPort === undefined) {
     throw new AgentKitError("runtime_error", "Could not determine the AgentKit dev server port.");
   }
 
+  const actualPort = start.actualPort;
+
   return {
     capsule,
     hostname,
+    requestedPort: options.port === undefined || options.port === 0 ? null : options.port,
     port: actualPort,
+    portConflict: start.portConflict,
     urls: {
       chat: `http://${hostname}:${actualPort}`,
       api: `http://${hostname}:${actualPort}/v1/chat`,
       inspect: `http://${hostname}:${actualPort}/_agentkit`,
     },
     storage: capsule.storagePath ? relativePath(capsule.root, capsule.storagePath) : null,
-    server,
+    server: start.server,
     async stop() {
-      await closeServer(server);
+      await closeServer(start.server);
     },
   };
 }
 
+async function listenForDevServer(
+  capsule: LoadedAgentCapsule,
+  hostname: string,
+  requestedPort: number,
+  autoPort: boolean,
+): Promise<{ server: Server; actualPort: number; portConflict: AgentDevServer["portConflict"] }> {
+  if (requestedPort === 0) {
+    const server = createDevHttpServer(capsule);
+    const actualPort = await listen(server, hostname, await findAvailablePort());
+    return { server, actualPort, portConflict: null };
+  }
+
+  let firstConflict: AgentDevServer["portConflict"] = null;
+  const lastPort = autoPort ? requestedPort + 50 : requestedPort;
+
+  for (let port = requestedPort; port <= lastPort; port += 1) {
+    const server = createDevHttpServer(capsule);
+
+    try {
+      const actualPort = await listen(server, hostname, port);
+      return { server, actualPort, portConflict: port === requestedPort ? null : firstConflict };
+    } catch (error) {
+      await closeServerAfterListenError(server);
+
+      if (!autoPort || !isAddressInUseError(error)) {
+        throw error;
+      }
+
+      firstConflict ??= {
+        port,
+        agent: await detectAgentKitOccupant(hostname, port),
+      };
+    }
+  }
+
+  throw new AgentKitError(
+    "runtime_error",
+    `Could not allocate a local AgentKit dev server port after ${requestedPort}-${lastPort}.`,
+  );
+}
+
+function createDevHttpServer(capsule: LoadedAgentCapsule): Server {
+  const channelDedupeKeys = new Set<string>();
+  return createHttpServer((incoming, outgoing) => {
+    void handleNodeRequest(capsule, incoming, outgoing, channelDedupeKeys);
+  });
+}
+
 async function handleNodeRequest(
   capsule: LoadedAgentCapsule,
   incoming: IncomingMessage,
@@ -163,9 +219,10 @@ async function handleDevServerRequest(
 
     if (request.method === "POST" && (route === "/v1/chat" || route === "/chat")) {
       const body = await readJsonBody(request);
-      const message = readUserMessage(body);
+      const { message, conversationId } = readChatRequest(body);
       const result = await runAgentMessage(capsule, {
         message,
+        conversationId,
         signal: request.signal,
       });
 
@@ -280,6 +337,7 @@ async function handlePortableChannel(
 
     const result = await runAgentMessage(capsule, {
       message: event.message.content,
+      conversationId: channelConversationId(channel.name, event.externalIdentity.key),
       signal: request.signal,
     });
     deliveries.push({
@@ -377,20 +435,61 @@ async function readJsonBody(request: Request): Promise<unknown> {
   }
 }
 
-function readUserMessage(body: unknown): string {
-  if (!isRecord(body) || !isRecord(body.message)) {
+function readChatRequest(body: unknown): { message: string; conversationId?: string } {
+  if (!isRecord(body)) {
+    throw new AgentKitError(
+      "validation_error",
+      'Expected body shape: {"message":{"role":"user","content":"hello"},"conversationId":"optional-id"}.',
+    );
+  }
+
+  const message = readUserMessage(body.message);
+  const conversationId = readOptionalConversationId(body.conversationId);
+
+  return { message, conversationId };
+}
+
+function readUserMessage(message: unknown): string {
+  if (typeof message === "string") {
+    const content = message.trim();
+
+    if (!content) {
+      throw new AgentKitError("validation_error", "message must be a non-empty string.");
+    }
+
+    return content;
+  }
+
+  if (!isRecord(message)) {
     throw new AgentKitError("validation_error", 'Expected body shape: {"message":{"role":"user","content":"hello"}}.');
   }
 
-  if (body.message.role !== "user") {
+  if (message.role !== "user") {
     throw new AgentKitError("validation_error", 'message.role must be "user".');
   }
 
-  if (typeof body.message.content !== "string" || body.message.content.trim().length === 0) {
+  if (typeof message.content !== "string" || message.content.trim().length === 0) {
     throw new AgentKitError("validation_error", "message.content must be a non-empty string.");
   }
 
-  return body.message.content;
+  return message.content.trim();
+}
+
+function readOptionalConversationId(value: unknown): string | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new AgentKitError("validation_error", "conversationId must be a non-empty string when provided.");
+  }
+
+  return value.trim();
+}
+
+function channelConversationId(channelName: string, externalIdentityKey: string): string {
+  const hash = createHash("sha256").update(`${channelName}:${externalIdentityKey}`).digest("hex").slice(0, 32);
+  return `chn_${hash}`;
 }
 
 function readToolInput(body: unknown): unknown {
@@ -805,6 +904,7 @@ function renderChatApp(capsule: LoadedAgentCapsule, baseUrl: string, env: Record
       const textarea = document.querySelector("#message");
       const messages = document.querySelector("#messages");
       const button = form.querySelector("button");
+      let conversationId = null;
 
       function addMessage(role, content, className = "") {
         const wrapper = document.createElement("article");
@@ -830,7 +930,7 @@ function renderChatApp(capsule: LoadedAgentCapsule, baseUrl: string, env: Record
           const response = await fetch("/v1/chat", {
             method: "POST",
             headers: { "content-type": "application/json" },
-            body: JSON.stringify({ message: { role: "user", content } }),
+            body: JSON.stringify({ message: { role: "user", content }, conversationId }),
           });
           const data = await response.json();
 
@@ -838,6 +938,7 @@ function renderChatApp(capsule: LoadedAgentCapsule, baseUrl: string, env: Record
             throw new Error(data.error?.message || "Chat request failed.");
           }
 
+          conversationId = data.conversationId || conversationId;
           addMessage(data.message.role, data.message.content);
         } catch (error) {
           addMessage("error", error instanceof Error ? error.message : String(error), "error");
@@ -881,6 +982,19 @@ function listen(server: Server, hostname: string, port: number): Promise<number>
   });
 }
 
+async function closeServerAfterListenError(server: Server): Promise<void> {
+  if (!server.listening) {
+    try {
+      server.close();
+    } catch {
+      // The server never reached the listening state.
+    }
+    return;
+  }
+
+  await closeServer(server);
+}
+
 function closeServer(server: Server): Promise<void> {
   return new Promise((resolvePromise, reject) => {
     server.close((error) => {
@@ -894,6 +1008,30 @@ function closeServer(server: Server): Promise<void> {
   });
 }
 
+function isAddressInUseError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "EADDRINUSE";
+}
+
+async function detectAgentKitOccupant(hostname: string, port: number): Promise<string | undefined> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 300);
+
+  try {
+    const response = await fetch(`http://${hostname}:${port}/_agentkit`, { signal: controller.signal });
+    const payload = await response.json().catch(() => null);
+
+    if (payload && typeof payload === "object" && "agent" in payload && typeof payload.agent === "string") {
+      return payload.agent;
+    }
+  } catch {
+    return undefined;
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  return undefined;
+}
+
 function findAvailablePort(): Promise<number> {
   return new Promise((resolve, reject) => {
     const server = createNetServer();

package/src/runtime/runtime-contract.ts

@@ -42,17 +42,31 @@ export async function assertRuntimeContract(
   const chat = await fetchJson(`${baseUrl}/chat`, {
     method: "POST",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify({ message: { role: "user", content: "contract hello" } }),
+    body: JSON.stringify({ message: { role: "user", content: "my name is Ada" } }),
   });
   expect(chat.status).toBe(200);
   expect(chat.body).toMatchObject({
     message: {
       role: "assistant",
-      content: "Echo: contract hello",
+      content: "Echo: my name is Ada",
     },
   });
   expect(typeof chat.body.conversationId).toBe("string");
 
+  const continuedChat = await fetchJson(`${baseUrl}/chat`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ message: "what is my name?", conversationId: chat.body.conversationId }),
+  });
+  expect(continuedChat.status).toBe(200);
+  expect(continuedChat.body).toMatchObject({
+    conversationId: chat.body.conversationId,
+    message: {
+      role: "assistant",
+      content: "Your name is Ada.",
+    },
+  });
+
   const tool = await fetchJson(`${baseUrl}/tools/${encodeURIComponent(options.tool.name)}`, {
     method: "POST",
     headers: { "content-type": "application/json" },