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

package/src/cli/index.ts

@@ -29,6 +29,7 @@ import { AgentKitError, isAgentKitError } from "../runtime/errors";
 import { prepareVpsDeploy } from "../runtime/targets/vps/deploy";
 
 const defaultAgentKitCloudApiUrl = "https://agentkit-cloud.aibuilders.com.br";
+const defaultAgentKitDevPort = 4123;
 const defaultDeployChatAccessTokenName = "agentkit-chat-ui";
 const defaultDeployChatAccessTokenPath = ".agentkit/chat-access-token.json";
 
@@ -47,10 +48,11 @@ Usage:
   agentkit <command> [options]
 
 Start:
-  agentkit new <name> [--template blank|support] [--no-install]
+  agentkit new <name> [--template blank|support|dentista] [--no-install]
   agentkit dev
+  agentkit open
   agentkit chat-ui --deploy
-  agentkit chat --message <text>
+  agentkit chat --message <text> [--conversation-id <id>]
   agentkit inspect
 
 Build:
@@ -63,7 +65,8 @@ Deploy:
   agentkit login --token <token>
   agentkit deploy doctor
   agentkit secret set <NAME> --stdin
-  agentkit deploy
+  agentkit secret sync --from-local
+  agentkit deploy --smoke "hello"
   agentkit deploy status
 
 More:
@@ -79,10 +82,11 @@ function renderCommandReference(): string {
   return `AgentKit Command Reference
 
 Usage:
-  agentkit new <name> [--template blank|support] [--no-install]
-  agentkit dev
+  agentkit new <name> [--template blank|support|dentista] [--no-install]
+  agentkit dev [--port <number>]
+  agentkit open
   agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
-  agentkit chat --message <text>
+  agentkit chat --message <text> [--conversation-id <id>]
   agentkit tool <name> [--input <path-or-json>]
   agentkit db migrate
   agentkit db reset --yes
@@ -99,11 +103,12 @@ Usage:
   agentkit channels deliveries list <name> [--api <url>]
   agentkit channels deliveries show <delivery-id> [--api <url>]
   agentkit inspect
-  agentkit build [--target cloudflare]
+  agentkit build [--target cloudflare|container]
   agentkit login --token <token> [--api <url>]
   agentkit logout
-  agentkit deploy [--target cloudflare|vps] [--host <host>] [--api <url>] [--dry-run] [--anonymous] [--local-wrangler]
+  agentkit deploy [--target cloudflare|vps] [--host <host>] [--api <url>] [--dry-run] [--anonymous] [--local-wrangler] [--smoke <message>]
   agentkit deploy doctor [--api <url>] [--anonymous]
+  agentkit deploy smoke [--message <text>] [--api <url>]
   agentkit deploy status [--api <url>]
   agentkit deploy pause [--api <url>]
   agentkit deploy resume [--api <url>]
@@ -111,6 +116,7 @@ Usage:
   agentkit secret set <NAME> --stdin [--api <url>]
   agentkit secret set <NAME> --from-env [ENV_NAME] [--api <url>]
   agentkit secret set <NAME> --from-local-env [--api <url>]
+  agentkit secret sync --from-local [--api <url>]
   agentkit secret list [--api <url>]
   agentkit secret unset <NAME> [--api <url>]
   agentkit access token create <name> [--api <url>] [--out <path>]
@@ -131,6 +137,7 @@ Usage:
 Commands:
   new             Create a new Agent Capsule
   dev             Run the Agent Capsule locally
+  open            Open the local Agent Capsule UI if it is already running
   chat-ui         Run a local chat UI, optionally pointed at a hosted deploy
   chat            Send one message to the local Agent Capsule
   tool            Run one registered tool directly
@@ -154,8 +161,11 @@ Examples:
   agentkit new support-agent --template support
   cd support-agent
   agentkit dev
+  agentkit open
   agentkit tool lookup_order --input '{"orderId":"A100"}'
   agentkit eval run
+
+  agentkit new clara-dentista --template dentista
 `;
 }
 
@@ -192,6 +202,33 @@ function parseArgs(argv: string[]): ParsedArgs {
   return { command, positional, flags };
 }
 
+function isHelpRequested(args: ParsedArgs): boolean {
+  return args.flags.help === true || args.flags.h === true || args.positional.includes("--help") || args.positional.includes("-h");
+}
+
+function renderCommandHelp(command: string): string {
+  const usage: Record<string, string> = {
+    new: "agentkit new <name> [--template blank|support|dentista] [--no-install]",
+    dev: "agentkit dev [--port <number>]",
+    open: "agentkit open",
+    "chat-ui": "agentkit chat-ui --deploy [--port <number>] [--token-file <path>]",
+    chat: 'agentkit chat --message "hello" [--conversation-id <id>]',
+    tool: "agentkit tool <name> [--input <path-or-json>]",
+    deploy:
+      'agentkit deploy [--smoke "hello"] | agentkit deploy smoke [--message "hello"] | agentkit deploy doctor | status | pause | resume',
+    secret:
+      "agentkit secret set <NAME> --stdin | --from-env [ENV_NAME] | --from-local-env | agentkit secret sync --from-local | list | unset <NAME>",
+    access: "agentkit access token create <name> [--out <path>] | list | revoke <token-id>",
+    env: "agentkit env set <NAME> --stdin | --from-env [ENV_NAME] | list | unset <NAME>",
+    docs: "agentkit docs path | llms | full",
+    handoff: "agentkit handoff codex [goal] | agentkit handoff claude [goal]",
+  };
+
+  return `Usage: ${usage[command] ?? "agentkit <command> [options]"}
+
+Run \`agentkit help commands\` for the full command reference.`;
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
 
@@ -200,6 +237,11 @@ async function main() {
     return;
   }
 
+  if (isHelpRequested(args)) {
+    console.log(renderCommandHelp(args.command));
+    return;
+  }
+
   if (args.command === "help") {
     const [topic] = args.positional;
 
@@ -222,7 +264,7 @@ async function main() {
     const shouldInstall = args.flags["no-install"] !== true;
 
     if (!name) {
-      throw new Error("Missing project name. Usage: agentkit new <name> [--template blank|support] [--no-install]");
+      throw new Error("Missing project name. Usage: agentkit new <name> [--template blank|support|dentista] [--no-install]");
     }
 
     const result = await createProject({ name, template, cwd: process.cwd() });
@@ -254,10 +296,17 @@ async function main() {
 
   if (args.command === "dev") {
     const port = parsePort(args.flags.port, "agentkit dev --port <number>");
-    const devServer = await startAgentDevServer(process.cwd(), { port });
+    const devServer = await startAgentDevServer(process.cwd(), { port, basePort: localDevBasePort() });
 
     console.log("Agent Capsule running");
     console.log("");
+    if (devServer.portConflict) {
+      const owner = devServer.portConflict.agent ? ` by ${devServer.portConflict.agent}` : "";
+      console.log(
+        `Port ${devServer.portConflict.port} is already used${owner}. Started ${devServer.capsule.config.name} at ${devServer.urls.chat}.`,
+      );
+      console.log("");
+    }
     console.log(`Chat:      ${devServer.urls.chat}`);
     console.log(`API:       ${devServer.urls.api}`);
     console.log(`Inspect:   ${devServer.urls.inspect}`);
@@ -266,6 +315,20 @@ async function main() {
     return;
   }
 
+  if (args.command === "open") {
+    const server = await findRunningLocalDevServer(process.cwd());
+
+    if (!server) {
+      console.log("No running AgentKit dev server found for this capsule.");
+      console.log("Run: npm run dev");
+      return;
+    }
+
+    await openLocalUrl(server.url);
+    console.log(`Opened ${server.url}`);
+    return;
+  }
+
   if (args.command === "chat-ui") {
     if (!args.flags.deploy) {
       throw new Error("Usage: agentkit chat-ui --deploy [--port <number>] [--token-file <path>]");
@@ -290,12 +353,17 @@ async function main() {
 
   if (args.command === "chat") {
     const message = args.flags.message;
+    const conversationId = parseOptionalStringFlag(
+      args.flags["conversation-id"] ?? args.flags.conversation,
+      "conversation id",
+      'agentkit chat --message "hello" [--conversation-id <id>]',
+    );
 
     if (typeof message !== "string") {
-      throw new Error('Missing message. Usage: agentkit chat --message "hello"');
+      throw new Error('Missing message. Usage: agentkit chat --message "hello" [--conversation-id <id>]');
     }
 
-    const result = await runAgentMessageFromCwd(process.cwd(), { message });
+    const result = await runAgentMessageFromCwd(process.cwd(), { message, conversationId });
     console.log(result.message.content);
     return;
   }
@@ -485,6 +553,20 @@ async function main() {
   if (args.command === "deploy") {
     const [deploySubcommand] = args.positional;
 
+    if (deploySubcommand === "smoke") {
+      const message =
+        parseOptionalStringFlag(args.flags.message ?? args.flags.smoke, "message", 'agentkit deploy smoke --message "hello"') ??
+        "hello";
+      const state = await requireLocalDeployState();
+      const token = await readDeployAccessTokenForSmoke(process.cwd(), state);
+      await runDeploySmoke({
+        deployUrl: requireDeployUrl(state),
+        message,
+        token,
+      });
+      return;
+    }
+
     if (deploySubcommand === "doctor") {
       const report = await checkDeployReadiness({
         apiUrl: await resolveCloudApiUrl(args.flags.api),
@@ -520,6 +602,7 @@ async function main() {
 
     const target = resolveDeployTarget(parseTargetFlag(args.flags.target, "deploy"));
     const anonymous = Boolean(args.flags.anonymous);
+    const smokeMessage = parseOptionalStringFlag(args.flags.smoke, "smoke", 'agentkit deploy --smoke "hello"');
 
     if (target.id === "vps") {
       const host = parseRequiredStringFlag(args.flags.host, "host", "agentkit deploy --target vps --host <host>");
@@ -592,6 +675,24 @@ async function main() {
       console.log(`Chat auth: could not create local chat token. ${formatReadinessError(chatAccess.error)}`);
       console.log(`Run:       agentkit access token create ${defaultDeployChatAccessTokenName} --out ${defaultDeployChatAccessTokenPath}`);
     }
+
+    if (smokeMessage) {
+      if (chatAccess?.status === "failed") {
+        throw new AgentKitError("deploy_smoke_failed", "Could not run deploy smoke because chat access token creation failed.");
+      }
+
+      await runDeploySmoke({
+        deployUrl: requireDeployUrl({
+          deploy_id: deploy.deploy.id,
+          url: deploy.deploy.url,
+        }),
+        message: smokeMessage,
+        token:
+          chatAccess?.status === "ready"
+            ? await readDeployAccessTokenForUi(chatAccess.path)
+            : undefined,
+      });
+    }
     return;
   }
 
@@ -617,6 +718,7 @@ async function main() {
         fromLocalEnvFlag: args.flags["from-local-env"],
         localEnvRoot: args.flags["from-local-env"] !== undefined ? await findAgentCapsuleRoot(process.cwd()) : undefined,
         usage: "agentkit secret set <NAME> <VALUE> | agentkit secret set <NAME> --stdin | agentkit secret set <NAME> --from-env [ENV_NAME] | agentkit secret set <NAME> --from-local-env [--api <url>]",
+        inlineSensitiveHelp: "Prefer --stdin, --from-env, or --from-local-env so the value does not enter shell history.",
       });
 
       if (!name) {
@@ -631,6 +733,15 @@ async function main() {
       return;
     }
 
+    if (subcommand === "sync") {
+      if (args.flags["from-local"] !== true) {
+        throw new Error("Usage: agentkit secret sync --from-local [--api <url>]");
+      }
+
+      await syncHostedSecretsFromLocal({ apiUrl, projectId });
+      return;
+    }
+
     if (subcommand === "unset") {
       if (!name) {
         throw new Error("Usage: agentkit secret unset <NAME> [--api <url>]");
@@ -643,7 +754,7 @@ async function main() {
       return;
     }
 
-    throw new Error("Usage: agentkit secret set <NAME> <VALUE> | agentkit secret set <NAME> --stdin | agentkit secret set <NAME> --from-env [ENV_NAME] | agentkit secret set <NAME> --from-local-env | agentkit secret list | agentkit secret unset <NAME>");
+    throw new Error("Usage: agentkit secret set <NAME> <VALUE> | agentkit secret set <NAME> --stdin | agentkit secret set <NAME> --from-env [ENV_NAME] | agentkit secret set <NAME> --from-local-env | agentkit secret sync --from-local | agentkit secret list | agentkit secret unset <NAME>");
   }
 
   if (args.command === "access") {
@@ -718,6 +829,7 @@ async function main() {
         fromEnvFlag: args.flags["from-env"],
         fromLocalEnvFlag: undefined,
         usage: "agentkit env set <NAME> <VALUE> | agentkit env set <NAME> --stdin | agentkit env set <NAME> --from-env [ENV_NAME]",
+        inlineSensitiveHelp: "Prefer --stdin or --from-env so the value does not enter shell history.",
       });
 
       if (!name) {
@@ -803,9 +915,12 @@ Rules:
 - Follow the AgentKit contract in llms-full.txt.
 - Treat the owner's request as the brief.
 - Build or update the agent inside this capsule as far as you can without asking for obvious restatements.
+- Do not wait for a wizard or recipe; implement directly in the capsule files.
 - Edit agent behavior in prompts/instructions.md.
 - Edit the agent contract in agentkit.config.ts.
 - Add TypeScript tools under tools/.
+- Keep the first useful version runnable with test/fake unless the owner has already chosen a real provider.
+- Before testing real conversation behavior, ask the owner to choose OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
 - Keep local secrets in .env only.
 - Do not commit or print secret values.
 - Do not edit .agentkit/ directly.
@@ -827,10 +942,16 @@ If you add a tool, also run a tool smoke test with the fake provider, for exampl
 npm run agentkit -- tool tool_name --input '{}'
 \`\`\`
 
+UI testing:
+- For local UI testing, run \`npm run dev\`, open the printed \`Chat:\` URL, and tell the owner the exact URL.
+- For hosted UI testing after deploy, run \`npm run agentkit -- chat-ui --deploy\`, open the printed \`Chat:\` URL, and tell the owner it is connected to the hosted deploy.
+- If the provider is still \`test/fake\`, say the UI was tested only with the deterministic fake provider.
+
 Final response:
 - Summarize what changed.
 - List files changed.
 - Paste the verification commands and results.
+- State whether testing used \`test/fake\` or a real provider selected by the owner.
 - Call out any missing user details or blocked checks.
 `;
 }
@@ -1142,6 +1263,38 @@ function secretSetCommand(secret: string, source: DeployReadinessContext["localS
   return `agentkit secret set ${secret} --stdin`;
 }
 
+async function syncHostedSecretsFromLocal(options: { apiUrl: string; projectId: string }): Promise<void> {
+  const context = await loadDeployReadinessContext(process.cwd(), process.env);
+  const localEnv = await loadCapsuleEnv(context.root, {});
+  let synced = 0;
+  let skipped = 0;
+
+  for (const secret of context.userManagedSecrets) {
+    const value = localEnv[secret];
+
+    if (value === undefined) {
+      skipped += 1;
+      console.log(`${secret}\tskipped_missing_local`);
+      continue;
+    }
+
+    await cloudApiRequest(options.apiUrl, `/v1/projects/${encodeURIComponent(options.projectId)}/secrets/${encodeURIComponent(secret)}`, {
+      method: "PUT",
+      body: JSON.stringify({ value }),
+    });
+    synced += 1;
+    console.log(`${secret}\tsynced`);
+  }
+
+  if (context.userManagedSecrets.length === 0) {
+    console.log("No user-managed hosted secrets are declared by this capsule.");
+    return;
+  }
+
+  console.log("");
+  console.log(`${synced} synced, ${skipped} skipped`);
+}
+
 function normalizeOptionalNumber(value: number | null | undefined): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
@@ -1158,6 +1311,10 @@ function isString(value: unknown): value is string {
   return typeof value === "string";
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
   const [subcommand, first, second, third] = args.positional;
 
@@ -1756,6 +1913,65 @@ async function requireLocalDeployState(): Promise<LocalDeployState> {
   return state;
 }
 
+function requireDeployUrl(state: Pick<LocalDeployState, "deploy_id" | "url">): string {
+  if (!state.url) {
+    throw new Error(`Deploy ${state.deploy_id} does not have a URL. Run agentkit deploy again.`);
+  }
+
+  return state.url;
+}
+
+async function readDeployAccessTokenForSmoke(cwd: string, state: LocalDeployState): Promise<string | undefined> {
+  if (state.access?.mode === "public") {
+    return undefined;
+  }
+
+  const root = await findAgentCapsuleRoot(cwd);
+  return readDeployAccessTokenForUi(join(root, defaultDeployChatAccessTokenPath));
+}
+
+async function runDeploySmoke(input: { deployUrl: string; message: string; token?: string }): Promise<void> {
+  const headers = new Headers({ "Content-Type": "application/json" });
+
+  if (input.token) {
+    headers.set("Authorization", `Bearer ${input.token}`);
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetch(new URL("/v1/chat", input.deployUrl).href, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ message: input.message }),
+    });
+  } catch (error) {
+    throw new AgentKitError(
+      "deploy_smoke_failed",
+      `Deploy smoke request failed before a response: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    throw new AgentKitError("deploy_smoke_failed", readCloudError(payload, response.status));
+  }
+
+  const content =
+    payload && typeof payload === "object" && "message" in payload && isRecord((payload as { message?: unknown }).message)
+      ? (payload as { message: { content?: unknown } }).message.content
+      : undefined;
+
+  console.log("");
+  console.log("Deploy smoke verified");
+  console.log(`URL:      ${input.deployUrl}`);
+  console.log(`Message:  ${input.message}`);
+  if (typeof content === "string") {
+    console.log(`Response: ${content}`);
+  }
+}
+
 async function resolveProjectIdForSecretCommand(cwd: string): Promise<string> {
   const state = await readLocalDeployStateIfExists(cwd);
 
@@ -1951,8 +2167,9 @@ async function resolveSecretInputValue(options: {
   fromLocalEnvFlag: string | boolean | undefined;
   localEnvRoot?: string;
   usage: string;
+  inlineSensitiveHelp?: string;
 }): Promise<string> {
-  const { name, valueParts, stdinFlag, fromEnvFlag, fromLocalEnvFlag, localEnvRoot, usage } = options;
+  const { name, valueParts, stdinFlag, fromEnvFlag, fromLocalEnvFlag, localEnvRoot, usage, inlineSensitiveHelp } = options;
 
   if (!name) {
     throw new Error(`Missing name. Usage: ${usage}`);
@@ -1972,6 +2189,11 @@ async function resolveSecretInputValue(options: {
 
   if (hasInlineValue) {
     value = valueParts.join(" ");
+    if (looksLikeSecretName(name)) {
+      console.error(
+        `Warning: ${name} looks sensitive. ${inlineSensitiveHelp ?? "Prefer --stdin or --from-env so the value does not enter shell history."}`,
+      );
+    }
   } else if (hasStdin) {
     if (stdinFlag !== true) {
       throw new Error(`--stdin does not take a value. Usage: ${usage}`);
@@ -2013,6 +2235,10 @@ async function resolveSecretInputValue(options: {
   return value;
 }
 
+function looksLikeSecretName(name: string): boolean {
+  return /(?:SECRET|TOKEN|KEY|PASSWORD|CREDENTIAL|PRIVATE)/i.test(name);
+}
+
 async function readStdinText(): Promise<string> {
   const chunks: Buffer[] = [];
 
@@ -2147,6 +2373,84 @@ function parseJsonInput(source: string, label: string): unknown {
   }
 }
 
+async function findRunningLocalDevServer(cwd: string): Promise<{ url: string; agent: string } | null> {
+  const capsule = await loadAgentCapsule(cwd);
+  const basePort = localDevBasePort();
+
+  for (let port = basePort; port <= basePort + 50; port += 1) {
+    const state = await fetchLocalAgentKitState(`http://localhost:${port}/_agentkit`);
+
+    if (state?.agent === capsule.config.name) {
+      return {
+        url: `http://localhost:${port}`,
+        agent: state.agent,
+      };
+    }
+  }
+
+  return null;
+}
+
+function localDevBasePort(): number {
+  const value = process.env.AGENTKIT_DEV_BASE_PORT;
+
+  if (!value) {
+    return defaultAgentKitDevPort;
+  }
+
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535 ? parsed : defaultAgentKitDevPort;
+}
+
+async function fetchLocalAgentKitState(url: string): Promise<{ agent?: string } | null> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 300);
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    const payload = await response.json().catch(() => null);
+
+    if (payload && typeof payload === "object") {
+      return {
+        agent: typeof (payload as { agent?: unknown }).agent === "string" ? (payload as { agent: string }).agent : undefined,
+      };
+    }
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  return null;
+}
+
+async function openLocalUrl(url: string): Promise<void> {
+  if (process.env.AGENTKIT_OPEN_COMMAND === "none") {
+    return;
+  }
+
+  const command =
+    process.env.AGENTKIT_OPEN_COMMAND ??
+    (process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open");
+  const args = process.env.AGENTKIT_OPEN_COMMAND
+    ? [url]
+    : process.platform === "win32"
+      ? ["/c", "start", "", url]
+      : [url];
+
+  await new Promise<void>((resolvePromise, reject) => {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.once("error", reject);
+    child.once("spawn", () => {
+      child.unref();
+      resolvePromise();
+    });
+  });
+}
+
 async function startDeployChatUiServer(
   cwd: string,
   options: { port: number; tokenFile?: string },

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;