@kohala/devkit 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @kohala/devkit
 
+## 0.1.2 (unreleased)
+
+- **`kohala validate` now rejects tool ids not in the bundled platform
+  catalog snapshot** (BUG-033). A typo'd tool id (e.g. `htpp.geet`) used to
+  pass validation and only fail at deploy/run time; it now fails validation
+  offline with the offending id(s) named. Pass `--allow-unknown-tools` to
+  bypass when the snapshot lags newly added platform tools — the deploy
+  endpoint still verifies against the live catalog authoritatively.
+
+- **Docs: LLM model-override env vars and `memory serve` agent scoping**
+  (BUG-047, BUG-035). The README now documents `KOHALA_LLM_MODEL`,
+  `ANTHROPIC_MODEL`, and `GEMINI_MODEL`, and clarifies that
+  `kohala memory serve` is always scoped to one agent (run it inside an
+  agent directory or pass `--agent <name>`).
+
+- **Repo hygiene: removed Replit workspace scaffolding from the repository**
+  (BUG-016). `.replit`, `replit.md`, `attached_assets/`, and `artifacts/`
+  are no longer tracked in the public repo.
+
+## 0.1.1
+
+Bug fixes.
+
+- **Default models updated to match the hosted platform** (BUG-040).
+  Local llm-mode now defaults to `claude-sonnet-4-6` (Anthropic) and
+  `gemini-flash-latest` (Gemini) — the same models the platform runs — so
+  cap tuning and output behaviour carry over after `kohala deploy`. Override
+  locally with `ANTHROPIC_MODEL`, `GEMINI_MODEL`, or `KOHALA_LLM_MODEL`.
+
+- **Default Gemini model changed from `gemini-2.0-flash` to
+  `gemini-flash-latest`** (BUG-041). The previous default hit quota limits
+  on new free-tier Gemini keys; the new default works on fresh keys.
+  Override with `GEMINI_MODEL` or `KOHALA_LLM_MODEL`.
+
+- **`kohala doctor` now correctly distinguishes llm-mode availability from
+  `llm.complete` availability** (BUG-042). `GEMINI_API_KEY` enables
+  `llm.complete` in wrap-mode skills but not the llm-mode tool-use loop
+  (which requires `ANTHROPIC_API_KEY`). The doctor now reports each case
+  separately so the output matches what actually works.
+
+- **`kohala run` error message is now specific when `runtimeMode: "llm"` is
+  used without an Anthropic key** (BUG-042). The previous message suggested
+  that `GEMINI_API_KEY` would work; the new message explains the distinction.
+
+- **`docs/` and `examples/` included in the published tarball** (BUG-034).
+  The README links to both; they now ship inside the package so installed
+  users can read them without cloning the repository.
+
+- **`kohala memory serve` documentation clarified** (BUG-035). The command
+  requires either `--agent <name>` or to be run from inside an agent
+  directory. The docs now show both forms.
+
 ## 0.1.0
 
 Initial release.
@@ -13,3 +65,9 @@ Initial release.
 - Stdlib-only Python script SDK over a loopback RPC boundary
 - Deploy client for the kohala.ai REST API (idempotent, additive,
   `--dry-run`)
+
+### SDK compatibility note (BUG-015)
+
+0.1.0 was released against `@kohala/sdk` 0.1.x. The SDK published 0.2.0 on
+2026-07-20 with updated method signatures. The emulator and deploy client
+work against any SDK version; this note tracks awareness of the divergence.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in
+the Kohala Devkit project a harassment-free experience for everyone,
+regardless of age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community and the project
+
+Examples of unacceptable behavior:
+
+- Harassment, trolling, insulting or derogatory comments, personal attacks
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at conduct@kohala.ai. All complaints will be
+reviewed and investigated promptly and fairly. Maintainers are obligated to
+respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to the Kohala Devkit
+
+Thanks for helping! The devkit is deliberately small and boring — please keep
+it that way.
+
+## Setup
+
+```bash
+git clone https://github.com/kohala-ai/devkit
+cd devkit
+npm install         # or pnpm install
+npm run build
+node dist/cli/index.js --version
+```
+
+Python 3 must be on your PATH to run the end-to-end tests.
+
+## Development loop
+
+```bash
+npm run typecheck   # strict tsc, no emit
+npm run lint        # eslint
+npm test            # vitest (unit + CLI e2e)
+npm run build       # tsup -> dist/
+```
+
+## Ground rules
+
+- **Errors fail loudly.** No silent fallbacks, no mock LLM responses, no
+  swallowed exceptions. If something can't work, say so with an actionable
+  message.
+- **Platform parity is the product.** Tool names, manifest fields, cap codes
+  (`PER_RUN_TOKEN_CAP`, `PER_DAY_TOKEN_CAP`, `TOOL_DENIED`), and enforcement
+  order must match the hosted platform. Don't rename things casually.
+- **Dependency budget.** Runtime deps are limited to: commander, zod,
+  @modelcontextprotocol/sdk, execa, picocolors, ora. `pg` stays an optional
+  peer. New runtime dependencies need a strong justification in the PR.
+- **The Python SDK stays stdlib-only.** Scaffolded agents must run without a
+  single `pip install`.
+- Keep CLI command files thin; put behavior in the library modules where it
+  can be unit-tested.
+
+## Submitting changes
+
+1. Fork, branch, make the change, add/adjust tests.
+2. Add a changeset: `npx changeset` (pick patch/minor and write one line).
+3. Open a PR. CI runs typecheck, lint, tests, and build on Node 20 and 22.
+
+## Releases
+
+Releases are automated with [changesets](https://github.com/changesets/changesets):
+merged changesets accumulate, and the release workflow versions, tags, and
+publishes to npm.

package/README.md

@@ -55,9 +55,11 @@ skill scripts).
 ```
 
 - `runtimeMode: "wrap"` executes your script directly and validates its
-  output (stdout).
-- `runtimeMode: "llm"` runs a real tool-use loop against **your own**
-  `ANTHROPIC_API_KEY` — the devkit never mocks completions.
+  output (stdout). Use `llm.complete` from the script SDK to call an LLM
+  mid-script (needs `ANTHROPIC_API_KEY` or `GEMINI_API_KEY`).
+- `runtimeMode: "llm"` runs a real Anthropic tool-use loop — requires
+  `ANTHROPIC_API_KEY`. `GEMINI_API_KEY` works for `llm.complete` in wrap
+  mode but not for this loop. The devkit never mocks completions.
 
 ## Docs
 
@@ -91,3 +93,24 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and PRs welcome.
 ## License
 
 [MIT](LICENSE)
+
+### LLM model overrides (local emulator)
+
+`kohala run` in LLM mode picks its model from environment variables:
+
+| Variable | Effect |
+| --- | --- |
+| `KOHALA_LLM_MODEL` | Provider-agnostic override — takes precedence over the two below. |
+| `ANTHROPIC_MODEL` | Anthropic model id (e.g. `claude-3-5-haiku-latest`). |
+| `GEMINI_MODEL` | Gemini model id (e.g. `gemini-2.0-flash`). |
+
+Unset, the emulator uses its built-in defaults.
+
+### Memory server scoping
+
+`kohala memory serve` is always scoped to ONE agent. Either run it from inside
+an agent directory (one containing `kohala.json`) or pass `--agent <name>`:
+
+```bash
+kohala memory serve --agent my-agent --backend file
+```

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest published version of `@kohala/devkit` receives security
+fixes.
+
+## Reporting a vulnerability
+
+Please email **security@kohala.ai** with a description of the issue, steps to
+reproduce, and the version affected. Do **not** open a public GitHub issue
+for security reports.
+
+We aim to acknowledge reports within 3 business days.
+
+## Scope notes
+
+- The devkit runs agent scripts **you** wrote on **your** machine, with your
+  own credentials. It does not sandbox skill scripts — treat third-party
+  agent code like any other code you execute locally.
+- The `http.post_json` tool refuses private/internal targets: it validates
+  the hostname, every IP it resolves to (IPv4 and IPv6, including
+  IPv4-mapped, link-local, ULA, and CGNAT ranges), and re-validates each
+  redirect hop. A determined attacker with DNS rebinding at request time may
+  still find gaps — do not treat it as a hardened network boundary.
+- `kohala login` stores your API key at `~/.kohala/credentials.json` with
+  mode 600. The `KOHALA_API_KEY` environment variable always takes
+  precedence and is the recommended mechanism in CI.

package/dist/cli/index.js

@@ -190,12 +190,240 @@ function loadManifest(agentDir) {
   return result.data;
 }
 
+// src/manifest/known-tools.ts
+var KNOWN_TOOL_IDS = /* @__PURE__ */ new Set([
+  "http.get",
+  "http.brightdata",
+  "run_python_script",
+  "web.search",
+  "image.generate",
+  "code.run",
+  "s3.put",
+  "koan.publish",
+  "report.publish",
+  "email.send",
+  "send_email",
+  "email.user_send",
+  "email.user_inbox",
+  "calendar.user_events",
+  "calendar.user_create_event",
+  "whatsapp.user_send",
+  "whatsapp.user_inbox",
+  "linkedin.user_post",
+  "linkedin.user_profile",
+  "linkedin.org_posts",
+  "linkedin.org_stats",
+  "validate_output",
+  "html.parse",
+  "json.parse",
+  "csv.parse",
+  "canvas.message",
+  "canvas.request_approval",
+  "odoo.search_read",
+  "odoo.read",
+  "odoo.read_group",
+  "odoo.create",
+  "odoo.write",
+  "odoo.unlink",
+  "odoo.call_method",
+  "odoo.message_post",
+  "odoo.attachments.upload",
+  "aftership.create_tracking",
+  "aftership.get_tracking",
+  "aftership.list_trackings",
+  "aftership.update_tracking",
+  "aftership.delete_tracking",
+  "aftership.detect_courier",
+  "fedex.track",
+  "ups.track",
+  "era5.point_history",
+  "noaa.forecast",
+  "noaa.alerts",
+  "airlabs.flight",
+  "airlabs.schedules",
+  "adsb.aircraft_near",
+  "adsb.by_callsign",
+  "aftership.list_couriers",
+  "ga.run_report",
+  "ga.realtime_report",
+  "ga.get_metadata",
+  "ga.list_properties",
+  "epicor.query",
+  "epicor.list",
+  "epicor.get",
+  "epicor.create",
+  "epicor.update",
+  "epicor.call_method",
+  "ideogram.generate",
+  "ideogram.edit",
+  "ideogram.remix",
+  "ideogram.reframe",
+  "ideogram.replace_background",
+  "ideogram.upscale",
+  "ideogram.describe",
+  "elevenlabs.text_to_speech",
+  "elevenlabs.speech_to_text",
+  "elevenlabs.speech_to_speech",
+  "elevenlabs.sound_effects",
+  "elevenlabs.voice_isolator",
+  "elevenlabs.music",
+  "elevenlabs.dubbing",
+  "elevenlabs.dubbing_result",
+  "elevenlabs.voice_design",
+  "elevenlabs.list_voices",
+  "video.generate_social",
+  "video.generate_cinematic",
+  "video.generate_avatar",
+  "video.status",
+  "extract.fields",
+  "extract.receipt",
+  "extract.financial",
+  "extract.legal",
+  "extract.product_spec",
+  "extract.menu",
+  "extract.evaluate",
+  "memory.search",
+  "memory.remember",
+  "http.post_json",
+  "s3.list",
+  "s3.get",
+  "s3.delete",
+  "feed.fetch",
+  "text.diff",
+  "data.diff",
+  "pinecone.upsert",
+  "pinecone.query",
+  "pinecone.fetch",
+  "pinecone.delete",
+  "llm.complete",
+  "pdf.extract",
+  "geocode",
+  "slack.message",
+  "discord.message",
+  "schedule.next_run",
+  "schedule.last_run",
+  "metrics.record",
+  "vector.embed",
+  "sms.send",
+  "push.send",
+  "webhook.post",
+  "notify.send",
+  "agent.handoff",
+  "bus.publish",
+  "bus.subscribe",
+  "bus.list_subscriptions",
+  "bus.unsubscribe",
+  "invoice.record",
+  "invoice.generate",
+  "invoice.modify",
+  "invoice.list",
+  "invoice.publish_koan",
+  "invoice.ap_run",
+  "invoice.ap_sweep",
+  "invoice.ar_sweep",
+  "invoice.ar_draft",
+  "invoice.send",
+  "invoice.review",
+  "invoice.calibrate",
+  "invoice.settings",
+  "invoice.status",
+  "sales_agreement.record",
+  "sales_agreement.review",
+  "sales_agreement.list",
+  "sales_agreement.publish_koan",
+  "customers.list",
+  "customers.add",
+  "customers.get_brand_profile",
+  "secrets.get",
+  "secrets.set",
+  "secrets.list",
+  "secrets.delete",
+  "aws.ec2_list",
+  "aws.ec2_start",
+  "aws.ec2_stop",
+  "aws.s3_list",
+  "aws.lambda_list",
+  "aws.lambda_invoke",
+  "aws.cloudwatch_alarms",
+  "aws.cost_summary",
+  "aws.rds_list",
+  "aws.bedrock_models",
+  "aws.grafana_list",
+  "googleads.list_accounts",
+  "googleads.search",
+  "googleads.campaign_performance",
+  "googleads.ad_group_performance",
+  "googleads.keyword_performance",
+  "googleads.budget_summary",
+  "calendar.generate",
+  "content.analyze",
+  "finance.ar.summary",
+  "finance.ar_aging",
+  "finance.ar_pastdue_report",
+  "finance.ar_overdue_notify",
+  "finance.ap.summary",
+  "finance.ap_aging",
+  "finance.reporting.summary",
+  "finance.trial_balance",
+  "sales.pipeline.summary",
+  "sales.pipeline_read",
+  "inventory.stock.summary",
+  "inventory.procurement_read",
+  "slack.list_channels",
+  "slack.post_message",
+  "notion.search",
+  "notion.append_page",
+  "hubspot.list_engagements",
+  "hubspot.log_call",
+  "hubspot.update_deal",
+  "linear.create_issue",
+  "asana.create_task",
+  "airtable.list_records",
+  "airtable.create_record",
+  "pandadoc.create_document",
+  "canva.create_design",
+  "canva.autofill_deck",
+  "zapier.trigger_zap",
+  "commitments.recall",
+  "workspacesync.fanout",
+  "dealdesk.draft",
+  "pricing.catalog_list",
+  "pricing.assumptions_list",
+  "pricing.benchmark_list",
+  "pricing.single_use_list",
+  "pricing.reusable_tco_list",
+  "pricing.monitoring_list",
+  "pricing.simulate_save"
+]);
+function unknownToolIds(tools) {
+  return tools.filter((t) => !KNOWN_TOOL_IDS.has(t));
+}
+
 // src/cli/validate.ts
 function registerValidateCommand(program2) {
-  program2.command("validate").argument("<agent>", "agent directory (containing kohala.json)").description("Validate an agent's kohala.json and print precise errors").action((agent) => {
+  program2.command("validate").argument("<agent>", "agent directory (containing kohala.json)").option(
+    "--allow-unknown-tools",
+    "do not fail on tool ids missing from the bundled catalog snapshot"
+  ).description("Validate an agent's kohala.json and print precise errors").action((agent, options) => {
     const agentDir = path3.resolve(process.cwd(), agent);
     try {
       const manifest = loadManifest(agentDir);
+      const unknown = unknownToolIds(manifest.toolAllowlist);
+      if (unknown.length > 0) {
+        const msg = `toolAllowlist contains tool id(s) not in the Kohala tool catalog: ` + unknown.join(", ");
+        if (options.allowUnknownTools) {
+          console.warn(pc2.yellow(`warning: ${msg}`));
+        } else {
+          console.error(pc2.red(msg));
+          console.error(
+            pc2.dim(
+              "  If these are new platform tools the bundled snapshot doesn't know yet, re-run with --allow-unknown-tools (the deploy endpoint will still verify against the live catalog)."
+            )
+          );
+          process.exitCode = 1;
+          return;
+        }
+      }
       console.log(pc2.green(`kohala.json for "${manifest.name}" is valid.`));
       console.log(
         pc2.dim(
@@ -725,8 +953,8 @@ var NoLlmKeyError = class extends Error {
     this.name = "NoLlmKeyError";
   }
 };
-var DEFAULT_ANTHROPIC_MODEL = "claude-3-5-haiku-latest";
-var DEFAULT_GEMINI_MODEL = "gemini-2.0-flash";
+var DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-6";
+var DEFAULT_GEMINI_MODEL = "gemini-flash-latest";
 function detectLlmProvider(env = process.env) {
   if (env.ANTHROPIC_API_KEY) return "anthropic";
   if (env.GEMINI_API_KEY) return "gemini";
@@ -735,10 +963,12 @@ function detectLlmProvider(env = process.env) {
 async function completeText(prompt, model, maxOutputTokens = 1024, env = process.env) {
   const provider = detectLlmProvider(env);
   if (provider === "anthropic") {
-    return completeAnthropic(prompt, model ?? DEFAULT_ANTHROPIC_MODEL, maxOutputTokens, env);
+    const resolvedModel = model ?? env.KOHALA_LLM_MODEL ?? env.ANTHROPIC_MODEL ?? DEFAULT_ANTHROPIC_MODEL;
+    return completeAnthropic(prompt, resolvedModel, maxOutputTokens, env);
   }
   if (provider === "gemini") {
-    return completeGemini(prompt, model ?? DEFAULT_GEMINI_MODEL, maxOutputTokens, env);
+    const resolvedModel = model ?? env.KOHALA_LLM_MODEL ?? env.GEMINI_MODEL ?? DEFAULT_GEMINI_MODEL;
+    return completeGemini(prompt, resolvedModel, maxOutputTokens, env);
   }
   throw new NoLlmKeyError();
 }
@@ -1211,9 +1441,11 @@ var TOOL_DEFINITIONS = {
 async function runLlmShift(context, skillName, scriptPath, repairFeedback) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
-    throw new NoLlmKeyError();
+    throw new Error(
+      'NO_LLM_KEY: llm mode requires ANTHROPIC_API_KEY. GEMINI_API_KEY enables llm.complete calls inside wrap-mode skills, but the llm-mode tool-use loop only supports Anthropic. Set ANTHROPIC_API_KEY in your environment to use runtimeMode: "llm".'
+    );
   }
-  const model = process.env.KOHALA_LLM_MODEL ?? "claude-3-5-haiku-latest";
+  const model = process.env.KOHALA_LLM_MODEL ?? process.env.ANTHROPIC_MODEL ?? "claude-sonnet-4-6";
   const dispatcher = new ToolDispatcher(context);
   const { manifest, meter, trace, runId } = context;
   const tools = Object.entries(TOOL_DEFINITIONS).filter(([name]) => manifest.toolAllowlist.includes(name)).map(([name, definition]) => ({ name: toApiToolName(name), ...definition }));
@@ -2198,8 +2430,15 @@ function registerDoctorCommand(program2) {
       warn("python 3 not found", "wrap-mode `kohala run --local` will not work until installed");
     }
     const provider = detectLlmProvider();
-    if (provider) {
-      ok(`LLM key (${provider})`, "llm.complete and llm mode available");
+    const hasAnthropic = Boolean(process.env.ANTHROPIC_API_KEY);
+    if (hasAnthropic) {
+      ok("LLM key (anthropic)", "llm.complete and llm mode both available");
+    } else if (provider === "gemini") {
+      ok("LLM key (gemini)", "llm.complete available in wrap mode");
+      warn(
+        "no ANTHROPIC_API_KEY",
+        'llm mode (runtimeMode: "llm") requires Anthropic \u2014 GEMINI_API_KEY covers llm.complete only'
+      );
     } else {
       warn(
         "no ANTHROPIC_API_KEY / GEMINI_API_KEY",