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

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/runtime/deploy.ts

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

package/src/runtime/targets/cloudflare/build.ts

@@ -662,6 +662,10 @@ export default {
       });
     }
 
+    if (request.method === "GET" && url.pathname === "/health") {
+      return Response.json({ status: "ok", agent: manifest.name });
+    }
+
     if (request.method === "POST" && (url.pathname === "/chat" || url.pathname === "/v1/chat")) {
       return handleChat(request, env);
     }

package/src/templates/blank.ts

@@ -156,7 +156,7 @@ Start building immediately:
 
 ## Local Commands
 
-- \`npm install\`: install capsule dependencies.
+- \`npm install\`: restore capsule dependencies if this capsule used \`--no-install\`, install failed, or \`node_modules\` was deleted.
 - \`npm run dev\`: run the local Agent Capsule runtime.
 - \`npm run chat -- --message "hello"\`: send one local chat message.
 - \`npm run eval\`: run agent evals.
@@ -166,7 +166,7 @@ Start building immediately:
 - \`npm run agentkit -- db seed --file seed.sql\`: apply local fixture data after migrate.
 - \`npm run agentkit -- db shell\`: inspect local development data when needed.
 - \`npm run agentkit -- inspect\`: print machine-readable capsule state.
-- \`npm run agentkit -- env set <NAME> <VALUE>\`: write a local secret value to ignored \`.env\`.
+- \`printf %s "$VALUE" | npm run agentkit -- env set <NAME> --stdin\`: write a local secret value to ignored \`.env\` without putting it in shell history.
 - \`npm run agentkit -- env list\`: list local secret names without printing values.
 - \`npm run agentkit -- docs full\`: print the full AgentKit contract path.
 
@@ -210,9 +210,9 @@ Use \`ctx.db\` as the canonical helper. \`ctx.database\` and \`ctx.storage.sql\`
 - AgentKit owns the hosted runtime, managed database, file storage, and production secret injection.
 - Local scaffold, dev, chat, eval, inspect, database, and build commands are token-free.
 - Hosted deploy requires an invited AgentKit Cloud alpha token. If no token is stored yet, ask the owner for one and run \`npm run agentkit -- login --token <token>\`.
-- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> <VALUE>\`, not into committed files.
+- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`, not into committed files or shell history.
 - The user should not choose a deploy target, create hosted databases, create buckets, copy production secrets into this capsule, or run operator/admin commands.
-- After a hosted deploy, create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\`.
+- Hosted deploy writes the local chat/UI deploy access token to \`.agentkit/chat-access-token.json\`. Create extra client-facing tokens with \`npm run agentkit -- access token create <name> --out <path>\`.
 
 ## Rules
 
@@ -249,16 +249,17 @@ Turn the request into a working local capsule:
 ## Local Commands
 
 \`\`\`sh
-npm install
 npm run typecheck
 npm run agentkit -- inspect
 npm run chat -- --message "hello"
 \`\`\`
 
+\`agentkit new\` installs dependencies by default. Run \`npm install\` only if the capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
+
 Set local development secrets without opening code:
 
 \`\`\`sh
-npm run agentkit -- env set OPENAI_API_KEY "<value>"
+printf %s "$OPENAI_API_KEY" | npm run agentkit -- env set OPENAI_API_KEY --stdin
 npm run agentkit -- inspect
 npm run chat -- --message "hello"
 \`\`\`
@@ -283,9 +284,9 @@ This capsule is hosted-deploy ready by default.
 2. Put agent-owned tables in \`schema.sql\`. AgentKit applies it locally and migrates/provisions hosted storage during deploy.
 3. Run \`npm run agentkit -- build\` only when you want to validate the artifact locally.
 4. If the owner has not logged in yet, ask for an invited AgentKit Cloud alpha token and run \`npm run agentkit -- login --token <token>\`.
-5. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> <VALUE>\`.
+5. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`.
 6. Run \`npm run agentkit -- deploy\`.
-7. Create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\` when a website or app needs to call the hosted agent.
+7. Run \`npm run agentkit -- chat-ui --deploy\` to test the hosted agent through a local UI using the auto-created \`.agentkit/chat-access-token.json\`. Create extra client-facing deploy access tokens with \`npm run agentkit -- access token create <name> --out <path>\` when a separate website or app needs its own credential.
 
 AgentKit owns hosted infrastructure and production secrets. Do not put production secret values in this capsule. Do not run operator/admin commands from a user capsule.
 `,
@@ -316,11 +317,12 @@ Generated by AgentKit as an Agent Capsule.
 ## Setup
 
 \`\`\`sh
-npm install
 npm run chat -- --message "hello"
 npm run dev
 \`\`\`
 
+\`agentkit new\` installs dependencies by default. Run \`npm install\` only if this capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
+
 \`agentkit.config.ts\` uses the built-in \`test/fake\` provider by default, so the first chat works without editing \`.env\`.
 When a real provider or tool needs a local development secret, keep the required name in \`.env.schema\`, keep the value in ignored \`.env\`, and run AgentKit commands normally; the local runtime loads \`.env\` directly.
 

package/src/templates/support.ts

@@ -199,13 +199,13 @@ Start building immediately:
 
 ## Local Commands
 
-- \`npm install\`: install capsule dependencies.
+- \`npm install\`: restore capsule dependencies if this capsule used \`--no-install\`, install failed, or \`node_modules\` was deleted.
 - \`npm run chat -- --message "hello"\`: send one local chat message.
 - \`npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'\`: test the example tool directly.
 - \`npm run eval\`: run agent evals.
 - \`npm run dev\`: run the local Agent Capsule runtime.
 - \`npm run agentkit -- inspect\`: print machine-readable capsule state.
-- \`npm run agentkit -- env set <NAME> <VALUE>\`: write a local secret value to ignored \`.env\`.
+- \`printf %s "$VALUE" | npm run agentkit -- env set <NAME> --stdin\`: write a local secret value to ignored \`.env\` without putting it in shell history.
 - \`npm run agentkit -- env list\`: list local secret names without printing values.
 - \`npm run agentkit -- docs full\`: print the full AgentKit contract path.
 
@@ -213,9 +213,9 @@ Start building immediately:
 
 - Local scaffold, chat, eval, dev, inspect, tool, and build commands are token-free.
 - Hosted deploy requires an invited AgentKit Cloud alpha token. If no token is stored yet, ask the owner for one and run \`npm run agentkit -- login --token <token>\`.
-- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> <VALUE>\`, not into committed files.
+- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`, not into committed files or shell history.
 - Deploy with \`npm run agentkit -- deploy\`, then check \`npm run agentkit -- deploy status\`.
-- Create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\` when a website or app needs to call the hosted agent.
+- Hosted deploy writes the local chat/UI deploy access token to \`.agentkit/chat-access-token.json\`. Create extra client-facing tokens with \`npm run agentkit -- access token create <name> --out <path>\` when a separate website or app needs its own credential.
 - Do not run operator/admin commands from a user capsule.
 
 ## Files
@@ -257,17 +257,18 @@ Turn the request into a working local capsule:
 ## Local Commands
 
 \`\`\`sh
-npm install
 npm run typecheck
 npm run agentkit -- inspect
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 npm run eval
 \`\`\`
 
+\`agentkit new\` installs dependencies by default. Run \`npm install\` only if the capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
+
 Set local development secrets without opening code:
 
 \`\`\`sh
-npm run agentkit -- env set OPENAI_API_KEY "<value>"
+printf %s "$OPENAI_API_KEY" | npm run agentkit -- env set OPENAI_API_KEY --stdin
 npm run agentkit -- inspect
 npm run chat -- --message "hello"
 \`\`\`
@@ -305,9 +306,9 @@ This capsule is deploy-ready by default.
 1. Keep tools edge-safe and use \`ctx.db\` instead of importing database drivers.
 2. Run \`npm run agentkit -- build\` only when you want to validate the artifact locally.
 3. If the owner has not logged in yet, ask for an invited AgentKit Cloud alpha token and run \`npm run agentkit -- login --token <token>\`.
-4. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> <VALUE>\`.
+4. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`.
 5. Run \`npm run agentkit -- deploy\`.
-6. Create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\` when a website or app needs to call the hosted agent.
+6. Run \`npm run agentkit -- chat-ui --deploy\` to test the hosted agent through a local UI using the auto-created \`.agentkit/chat-access-token.json\`. Create extra client-facing deploy access tokens with \`npm run agentkit -- access token create <name> --out <path>\` when a separate website or app needs its own credential.
 
 AgentKit owns hosted infrastructure and production secrets. Do not put production secret values in this capsule. Do not run operator/admin commands from a user capsule.
 `,
@@ -334,13 +335,14 @@ Generated by AgentKit as a support Agent Capsule.
 ## Setup
 
 \`\`\`sh
-npm install
 npm run chat -- --message "hello"
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 npm run eval
 npm run dev
 \`\`\`
 
+\`agentkit new\` installs dependencies by default. Run \`npm install\` only if this capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
+
 The support template includes a local \`lookup_order\` TypeScript tool and uses \`test/fake\` by default.
 `,
       },