@andreprado/agentkit 0.1.1 → 0.3.0

package/docs/guides/improve-from-production.md

@@ -1,151 +0,0 @@
-# Improve From Production
-
-## Goal
-
-Pull hosted or local conversation evidence into the Agent Capsule, turn it into regression evals, let the local coding agent patch the capsule, and replay before deploying again.
-
-## When To Use This
-
-Use this when a deployed agent gave a wrong answer, failed a tool call, mishandled a channel message, or needs production behavior converted into eval coverage.
-
-AgentKit Cloud only exports redacted evidence. The local coding agent owns source edits, evals, replay, and deploy.
-
-## Commands
-
-Collect evidence from the last hosted deploy:
-
-```sh
-agentkit improve collect --deploy --since 24h
-```
-
-When the CLI is logged in to AgentKit Cloud, this command first asks the control plane for deploy evidence such as failed channel deliveries, deploy errors, and conversation IDs that need review. It then reads replayable hosted conversation traces from the deployed runtime with the deploy access token. If Cloud auth is not available, it still collects hosted conversations directly from the deploy URL.
-
-Hosted conversation reads require a deploy access token even when the chat endpoint is public. `agentkit deploy` normally writes `.agentkit/chat-access-token.json`; refresh it with:
-
-```sh
-agentkit access token create agentkit-chat-ui --out .agentkit/chat-access-token.json
-```
-
-Collect one hosted conversation:
-
-```sh
-agentkit improve collect --deploy --conversation-id <conversation-id>
-```
-
-Collect local conversations instead:
-
-```sh
-agentkit improve collect --since 7d
-```
-
-Generate regression evals from the collected bundle:
-
-```sh
-agentkit improve evals .agentkit/improve/<run>
-```
-
-Replay the bundle against the local capsule:
-
-```sh
-agentkit replay .agentkit/improve/<run> --against local
-```
-
-## Files Created Or Edited
-
-Evidence bundle, ignored local state:
-
-```txt
-.agentkit/improve/<run>/
-  bundle.json
-  report.json
-  traces/
-```
-
-Generated regression evals, committed source:
-
-```txt
-evals/regressions/
-  improve-<conversation>.eval.ts
-```
-
-The local coding agent may then edit:
-
-```txt
-prompts/instructions.md
-agentkit.config.ts
-tools/
-knowledge/
-evals/
-```
-
-Do not edit `.agentkit/improve/<run>/bundle.json` by hand.
-
-## Workflow
-
-```sh
-agentkit improve collect --deploy --since 24h
-agentkit improve evals .agentkit/improve/<run>
-agentkit replay .agentkit/improve/<run> --against local
-```
-
-Then let the local coding agent inspect `report.json`, the generated eval files, prompts, tools, and Knowledge sources. After edits:
-
-```sh
-npm run typecheck
-npm run agentkit -- inspect
-npm run eval
-agentkit replay .agentkit/improve/<run> --against local
-agentkit deploy --smoke "hello"
-```
-
-## Safety Rules
-
-- Do not paste secrets into evals, prompts, Knowledge files, or reports.
-- Keep `.agentkit/improve/` out of commits.
-- Review generated eval assertions before committing them. AgentKit redacts common email, phone, bearer token, and key patterns in generated eval text, but the local coding agent must still remove or generalize domain-specific client PII.
-- For write, delete, payment, email, or customer-system tools, branch inside the tool on `ctx.runtime.environment === "eval"` and return deterministic non-destructive output.
-- Treat hosted traces as customer evidence.
-- If replay uses a real provider instead of `test/fake`, tell the owner because it may cost money and may be nondeterministic.
-
-## Verification
-
-```sh
-npm run typecheck
-npm run agentkit -- inspect
-npm run eval
-agentkit replay .agentkit/improve/<run> --against local
-```
-
-Expected:
-
-- `improve collect` writes a bundle and report under `.agentkit/improve/`.
-- Hosted collection includes a redacted `evidence` summary in `bundle.json` and `report.json` when AgentKit Cloud evidence export is available.
-- `improve evals` writes eval files under `evals/regressions/`.
-- `replay` reports passed, failed, and skipped traces.
-- No production secret values appear in generated files.
-
-## Troubleshooting
-
-`No .agentkit/deploy.json found`:
-
-Run `agentkit deploy` first, or collect local evidence without `--deploy`.
-
-`deploy_conversation_request_failed`:
-
-Refresh the deploy chat token with `agentkit access token create agentkit-chat-ui --out .agentkit/chat-access-token.json`, then retry.
-
-`improve_evidence_store_not_configured`:
-
-The Cloud API does not expose deploy evidence export yet. The CLI falls back to hosted conversation trace collection when possible.
-
-`conversation_access_not_configured`:
-
-The hosted runtime is not configured with a deploy access-token gate for conversation reads. Redeploy through AgentKit Cloud so the runtime gate is injected, or configure an explicit deploy/private token for local hosted testing.
-
-`trace has no user turns`:
-
-The trace cannot become a useful conversation eval. Keep the report for diagnosis, but do not commit an empty eval.
-
-Generated eval is too strict:
-
-Edit the eval to assert the important behavior, such as tool input, safety wording, or knowledge source usage, instead of exact prose.

package/docs/guides/prepare-deploy.md

@@ -1,227 +0,0 @@
-# Prepare Deploy
-
-## Goal
-
-Prepare an Agent Capsule so a coding agent can run the same workflow a user will run:
-
-```sh
-agentkit deploy
-```
-
-The agent should not choose hosting targets or infrastructure providers. AgentKit owns that routing.
-
-## When To Use This
-
-Use this before asking a coding agent to make a capsule deployable, or before testing the end-to-end user flow from a clean scaffold.
-
-## User Workflow
-
-From the capsule root:
-
-```sh
-npm run typecheck
-npm run agentkit -- inspect
-npm run agentkit -- db migrate
-npm run chat -- --message "hello"
-```
-
-All scaffold, local dev, chat, eval, inspect, database, and build commands are token-free. Hosted production deploy and hosted AgentKit Cloud changes require an AgentKit Cloud account token with hosted deploy access.
-
-If the user does not have a token yet, start checkout from the CLI, finish Stripe Checkout in the browser, then claim the one-time checkout intent:
-
-```sh
-npm run agentkit -- billing checkout --slots 1 --email user@example.com
-npm run agentkit -- billing claim billint_... --secret bsec_...
-```
-
-The claim command stores the returned `agk_user_...` token in the local AgentKit Cloud auth file. Treat the `bsec_...` checkout secret like a password; it exists only to claim the first token after checkout.
-
-If the user already has a token:
-
-```sh
-npm run agentkit -- login --token agk_user_...
-npm run agentkit -- deploy doctor
-npm run agentkit -- secret set OPENAI_API_KEY --from-local-env
-npm run agentkit -- deploy --smoke "hello"
-npm run agentkit -- chat-ui --deploy
-```
-
-If the capsule uses OpenAI locally, put the user’s local key in `.env`:
-
-```sh
-OPENAI_API_KEY=sk-...
-```
-
-`.env` is local-only. Hosted deploy secrets are handled by AgentKit outside the capsule.
-Hosted deploys require an account with either `cloudflare_deploy_alpha` or purchased/manual deploy slots. Deploy slots belong to the account, not to a specific token string.
-
-To generate or switch account tokens after login:
-
-```sh
-npm run agentkit -- account token create new-laptop --use
-npm run agentkit -- account token list
-npm run agentkit -- account token revoke apitok_...
-```
-
-## What The Agent Should Edit
-
-Review and edit:
-
-```txt
-agentkit.config.ts
-prompts/instructions.md
-tools/
-evals/
-.env.schema
-AGENTS.md
-CLAUDE.md
-README.md
-schema.sql
-```
-
-Never commit or deploy:
-
-```txt
-.env
-.agentkit/
-node_modules/
-```
-
-## Deploy-Ready Config Shape
-
-Use the AgentKit-managed storage contract. Do not make the user or the coding agent choose a backend target or infrastructure provider.
-
-```ts
-export default defineAgent({
-  name: "support-agent",
-  runtime: "edge",
-  provider: {
-    name: "openai",
-    model: "gpt-4o-mini",
-  },
-  instructions: "./prompts/instructions.md",
-  secrets: ["OPENAI_API_KEY"],
-  tools: [],
-  access: {
-    mode: "private",
-  },
-  storage: {
-    driver: "agentkit",
-  },
-});
-```
-
-This config is user-facing because it describes the agent contract: provider, prompts, tools, access, secrets, and managed storage. The concrete deploy target, database vendor, file bucket, and runtime host are not user-facing.
-
-If the generated capsule already includes a managed database block, keep the `schema` path correct and put tables in `schema.sql`. The concrete database vendor is an AgentKit implementation detail.
-
-## Database Rules
-
-For agent-owned tables:
-
-- Put tables and indexes in `schema.sql`.
-- Keep `schema.sql` idempotent.
-- Prefer `CREATE TABLE IF NOT EXISTS` and `CREATE INDEX IF NOT EXISTS`.
-- Use `agentkit db migrate` before local tool/chat testing.
-- Use `ctx.db` inside tools. `ctx.database` and `ctx.storage.sql` are aliases.
-- Do not import local database drivers from tools.
-
-Local commands use `.agentkit/agentkit.db`. Hosted deploy uses AgentKit-managed infrastructure.
-
-## Verification
-
-Run this before saying the capsule is deploy-ready:
-
-```sh
-npm run typecheck
-npm run agentkit -- inspect
-npm run agentkit -- db migrate
-npm run chat -- --message "hello"
-npm run agentkit -- deploy --dry-run
-npm run agentkit -- deploy doctor
-```
-
-For a final end-to-end test, run:
-
-```sh
-npm run agentkit -- login --token agk_user_...
-npm run agentkit -- account token list
-npm run agentkit -- secret sync --from-local
-npm run agentkit -- secret list
-npm run agentkit -- deploy --smoke "hello"
-npm run agentkit -- deploy status
-npm run agentkit -- chat-ui --deploy
-npm run agentkit -- access token list
-```
-
-For hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json` and prints a production handoff with the deploy URL, UI command, secret status, database/schema artifact, integration connect commands, smoke status, and next recommended command. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. The hosted Chat UI shows the conversation id, tool calls, tool errors, and a new-conversation control; use `npm run agentkit -- conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
-
-When the UI is running, open the printed `Chat:` URL and tell the owner the exact URL. If the capsule is still on `test/fake`, say the UI was tested only with the deterministic fake provider.
-
-## Readiness Checklist
-
-```txt
-No .env committed
-No .agentkit committed
-All required secret names are declared
-Prompt path exists
-Tools have input schemas
-Read-only tools use `:read` permissions; dangerous tools use operator-only non-read permissions
-Managed Composio toolkit auth configs are available in AgentKit Cloud when configured
-Provider model is supported by AgentKit
-schema.sql is idempotent
-README/AGENTS/CLAUDE match the capsule
-```
-
-## Troubleshooting
-
-`agentkit deploy` fails before publishing:
-
-Read the AgentKit error code first. Common fixes are:
-
-- run `npm run typecheck`;
-- run `npm run agentkit -- inspect`;
-- make tools edge-safe;
-- declare missing secret names in `agentkit.config.ts`;
-- keep production secret values out of source files.
-
-Missing local OpenAI key:
-
-```sh
-echo 'OPENAI_API_KEY=sk-...' >> .env
-```
-
-Missing hosted secret:
-
-Set the secret in AgentKit Cloud:
-
-```sh
-npm run agentkit -- secret set OPENAI_API_KEY --from-local-env
-```
-
-To sync all declared user-managed secrets present in local `.env`:
-
-```sh
-npm run agentkit -- secret sync --from-local
-```
-
-Do not write hosted secret values into the capsule.
-
-Before a hosted production deploy, run:
-
-```sh
-npm run agentkit -- deploy doctor
-```
-
-The doctor checks AgentKit Cloud login, Node version, hosted deploy entitlement, online deploy capacity, declared hosted secrets, local `.env` names that have not been uploaded with `npm run agentkit -- secret set`, and private-access runtime token handling. `agentkit deploy` runs the same readiness check automatically before building and uploading the artifact.
-
-If the capsule configures `composioManaged({...})`, the doctor also checks the paid `managed_composio` entitlement and AgentKit Cloud toolkit readiness. `COMPOSIO_API_KEY` and toolkit auth config resolution are AgentKit-managed in this path; the user must not set them with `agentkit secret set`.
-
-`alpha_access_required`:
-
-Log in with an account that has hosted deploy access. If the user needs to buy slots first:
-
-```sh
-npm run agentkit -- billing checkout --slots 1 --email user@example.com
-npm run agentkit -- billing claim billint_... --secret bsec_...
-```

package/docs/guides/replay-production-traces.md

@@ -1,72 +0,0 @@
-# Replay Production Traces
-
-## Goal
-
-Run collected production or local traces against the local Agent Capsule before redeploying a fix.
-
-## When To Use This
-
-Use this after `agentkit improve collect` and before `agentkit deploy` whenever prompts, tools, Knowledge, provider config, or channel behavior changed because of production evidence.
-
-## Commands
-
-```sh
-agentkit replay .agentkit/improve/<run> --against local
-```
-
-Run the full local eval suite too:
-
-```sh
-npm run eval
-```
-
-## What Replay Checks
-
-Replay sends each collected user turn through the local capsule in eval mode:
-
-```txt
-ctx.runtime.environment === "eval"
-ctx.runtime.invocation === "eval"
-```
-
-This proves the current capsule can process the production turns without runtime errors. Generated eval files under `evals/regressions/` add committed behavior assertions.
-
-## Write Tool Safety
-
-Replay still runs the registered capsule tools. Any tool that can write externally must guard eval mode:
-
-```ts
-if (ctx.runtime.environment === "eval") {
-  return { sent: false, evalFixture: true };
-}
-```
-
-Do not depend on prompt wording alone to prevent side effects.
-
-## Deploy Gate
-
-Before redeploying a production fix:
-
-```sh
-npm run typecheck
-npm run agentkit -- inspect
-npm run eval
-agentkit replay .agentkit/improve/<run> --against local
-agentkit deploy --smoke "hello"
-```
-
-If replay fails, inspect the failed trace id in `.agentkit/improve/<run>/traces/`, patch the capsule, and rerun replay.
-
-## Troubleshooting
-
-`Replay failed`:
-
-Read the printed error and the matching trace file. Common causes are missing local secrets, unsafe tools that do not branch on eval mode, stale Knowledge sources, or provider differences.
-
-`Replay skipped`:
-
-The trace had no user message. It may still help diagnose delivery or deploy state, but it cannot be replayed as a conversation.
-
-`provider_model_unsupported`:
-
-The local provider config does not match the replay environment. Keep deterministic regression replay on `test/fake` unless the owner intentionally selected a real provider.

package/docs/guides/send-feedback.md

@@ -1,135 +0,0 @@
-# Send Feedback To AgentKit
-
-## Goal
-
-Create a redacted local feedback draft when AgentKit itself is confusing, missing docs, or failing, then send it to AgentKit Cloud only after the user has authenticated.
-
-## When To Use This
-
-Use this for AgentKit product feedback, not for the user's agent's client conversations.
-
-Good cases:
-
-- an AgentKit CLI command failed and the error did not explain recovery;
-- a docs guide or generated skill is missing a step;
-- deploy, channel, provider, eval, or runtime behavior looks like an AgentKit bug;
-- the user's coding agent found a feature gap in AgentKit itself.
-
-Do not use this to upload private client data, provider keys, `.env` values, or full conversation transcripts.
-
-## Commands
-
-Create a local draft only:
-
-```sh
-agentkit feedback create --about last-run --kind bug --summary "Deploy failed after secrets sync"
-```
-
-Preview a draft:
-
-```sh
-agentkit feedback preview .agentkit/feedback/<draft>.json
-```
-
-Send a saved draft:
-
-```sh
-agentkit login --token agk_user_...
-agentkit feedback send .agentkit/feedback/<draft>.json
-```
-
-Create and send in one command:
-
-```sh
-agentkit feedback send --about deploy --kind deploy_issue --summary "Deploy doctor passed but deploy failed" --message "The recovery step was unclear."
-```
-
-## Files Created Or Edited
-
-`feedback create` writes ignored local files:
-
-```txt
-.agentkit/feedback/<timestamp>-<summary>.json
-.agentkit/feedback/<timestamp>-<summary>.md
-```
-
-These files are local diagnostic drafts. Keep `.agentkit/` out of commits.
-
-## Minimal Working Example
-
-```sh
-agentkit feedback create \
-  --about last-run \
-  --kind missing_docs \
-  --summary "The channel debug guide did not explain Discord bot mode recovery" \
-  --message "The command failed after setup, and I could not tell whether to rerun connect or setup."
-```
-
-Review the printed JSON path, then send it:
-
-```sh
-agentkit feedback send .agentkit/feedback/<draft>.json
-```
-
-## Safety Rules
-
-- Creating a draft never sends network feedback.
-- Sending requires AgentKit Cloud login.
-- The CLI redacts common bearer tokens, AgentKit tokens, provider key patterns, and Authorization headers before saving or sending.
-- AgentKit Cloud validates the payload again and stores the redacted report under the authenticated account.
-- Do not paste `.env` contents, provider key values, OAuth tokens, cookies, client PII, or full private transcripts into `--message`.
-- The feedback command does not upload arbitrary files and does not ask AgentKit Cloud to fetch URLs.
-- The deployed agent runtime does not send feedback to the AgentKit team.
-
-## Verification
-
-After creating a draft:
-
-```sh
-agentkit feedback preview .agentkit/feedback/<draft>.json
-```
-
-Expected:
-
-- `schema_version` is `agentkit.feedback.v1`;
-- `source.channel` is `cli`;
-- `context` describes the current capsule and deploy shape;
-- no secret values are present.
-
-After sending:
-
-```txt
-Feedback sent
-ID:     fb_...
-Status: new
-```
-
-## Troubleshooting
-
-`auth_required`:
-
-Log in before sending:
-
-```sh
-agentkit login --token agk_user_...
-```
-
-`feedback_draft_invalid`:
-
-Recreate the draft with `agentkit feedback create`. Do not hand-edit the JSON schema unless you keep `schema_version: "agentkit.feedback.v1"`.
-
-`payload_too_large`:
-
-Shorten `--message`. Do not paste full logs; include the command, exact error code, and the smallest useful excerpt.
-
-## Backend Contracts Used
-
-Feedback submit uses authenticated AgentKit Cloud account auth:
-
-```txt
-POST /v1/feedback
-Authorization: Bearer agk_user_...
-Idempotency-Key: fbdraft_...
-```
-
-The endpoint accepts only structured JSON feedback and stores it in the AgentKit Cloud feedback inbox.