@kohala/devkit 0.1.6 → 0.2.0

package/docs/DEPLOY.md

@@ -21,6 +21,7 @@ kohala deploy my-agent --dry-run   # print exactly what would be sent
 kohala deploy my-agent             # do it
 kohala deploy my-agent --run       # ...and trigger a manual hosted run
 kohala deploy my-agent --base-url https://staging.kohala.ai   # non-prod target
+kohala deploy my-agent --allow-unknown-packages               # skip the local npm allowlist check
 ```
 
 ## What deploy does
@@ -34,6 +35,14 @@ Deploy maps `kohala.json` onto the platform REST API, in order:
 4. (with `--run`) `POST /api/v1/agents/:id/agent-runs/manual` — trigger a
    run and print its URL.
 
+Each skill upload carries the script's runtime. Python skills are sent
+exactly as they always were; a TypeScript/JavaScript skill (`.ts`, `.js`, …)
+also sends `runtimeLanguage: "node"` and the manifest's `dependencies` as
+`scriptDependencies`. That is what makes the platform run its acceptance
+checks **when the script is attached** — TypeScript compile, security scan,
+and the npm allowlist — instead of letting the script fail on its first
+hosted run. The CLI prints the detected language for every skill it uploads.
+
 Deploy is **additive only** — it never deletes agents, skills, or memory
 remotely. Removing a skill from kohala.json does not remove it from the
 platform; do that in the Kohala dashboard.
@@ -44,5 +53,22 @@ platform; do that in the Kohala dashboard.
   fresh `pk_` key, or check `KOHALA_API_KEY`.
 - **403 Forbidden** — your plan does not allow the operation. Check your
   plan at kohala.ai.
+- **unsupported npm dependencies for framework "custom": …** — a package in
+  `dependencies` is not one the platform installs. The CLI reports this
+  before sending anything; the same message comes back from the platform if
+  you deploy with `--allow-unknown-packages`. See the allowlist in
+  [MANIFEST.md](MANIFEST.md#script-languages).
+- **Script rejected: TypeScript compile failed / security issue(s) found** —
+  the platform checks a TypeScript/JavaScript script when it is attached,
+  before storing it. Nothing is deployed; fix the reported lines and
+  redeploy.
+- **manual run not started: agent not enabled** — newly created agents start
+  disabled. Enable the agent in the kohala.ai dashboard, then re-run
+  `kohala deploy <agent> --run`. Enabling survives redeploys — the idempotent
+  upsert does not reset it.
+- **manual run not started: nothing to run** — the platform only executes
+  scripts bound to an active cron schedule. Add `"schedule": "..."` (a
+  5-field cron expression) to `kohala.json` and redeploy: deploy binds every
+  skill script to the schedule, which also makes manual runs work.
 
 Both messages tell you this directly; nothing is retried silently.

package/docs/MANIFEST.md

@@ -36,7 +36,8 @@ is what goes live.
 | `charter` | `agentCharter` | The agent's mission. In llm mode this is the system prompt. |
 | `toolAllowlist` | `agentToolAllowlist` | Exactly the tools the agent may call. No implicit grants. |
 | `runtimeMode` | `agentRuntimeMode` | `"wrap"` or `"llm"` (see below). |
-| `skills` | `agentSkills` | Map of skill name → script filename in `skills/`. |
+| `skills` | `agentSkills` | Map of skill name → script filename in `skills/`. The extension picks the runtime (see below). |
+| `dependencies` | `scriptDependencies` | npm packages the TypeScript/JavaScript skills import. Allowlisted packages only; omit for Python agents. |
 | `schedule` | `agentScheduleCron` + `agentScheduleEnabled` + `agentScheduleEntries` | Cron expression. Only used on deploy; local runs are manual. After uploading the skills, deploy PATCHes the schedule (the platform ignores schedule fields when updating an existing agent by name) **and binds every skill script to the cron via `agentScheduleEntries`** — without the binding the platform has nothing to run (409 `nothing_to_run`). The round-trip is verified. |
 | `caps.perRunTokens` | `agentPerRunTokenCap` | Hard token ceiling per shift. |
 | `caps.perDayTokens` | `agentPerDayTokenCap` | Cumulative ceiling per UTC day. |
@@ -44,6 +45,49 @@ is what goes live.
 | `caps.billingPeriod` | `agentBillingCapPeriod` | `"day"`, `"week"`, or `"month"`. Required with `billingTokens`. |
 | `validators` | agent validators | Output checks (below). |
 
+## Script languages
+
+A skill script can be Python or TypeScript/JavaScript. **The file extension
+decides which runtime the platform executes it in** — the same rule the
+platform applies, so what `kohala validate` reports is what runs hosted:
+
+| Extension | Runtime |
+| --- | --- |
+| `.py` | Python |
+| `.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs` | TypeScript/JavaScript |
+
+Anything else is refused by `kohala validate` — the platform would store the
+skill and never run it.
+
+```json
+{
+  "skills": { "collect": "main.ts" },
+  "dependencies": ["zod", "date-fns"]
+}
+```
+
+`dependencies` lists the npm packages your TypeScript skills import beyond
+Node's standard library, and is sent with the script on deploy. Only packages
+the platform pre-installs are accepted:
+
+`@ai-sdk/anthropic`, `@ai-sdk/openai`, `@anthropic-ai/sdk`, `ai`, `cheerio`,
+`date-fns`, `js-yaml`, `openai`, `zod`
+
+HTTP clients (`axios`, `node-fetch`, `undici`, …) are deliberately absent:
+the hosted runtime meters egress through the global `fetch`. `kohala
+validate` and `kohala deploy` refuse anything off the list **before** the
+deploy request, with the platform's own message; `--allow-unknown-packages`
+skips the local check if the CLI's snapshot is behind (the platform still
+enforces the live list).
+
+`dependencies` is npm-only. Python skills cannot install pip packages from
+the CLI, so declaring packages without a `.ts`/`.js` skill is a validation
+error rather than a silently ignored field.
+
+**Local runs:** `kohala run --local` executes Python skills only. A
+TypeScript skill deploys and runs hosted; locally the CLI says so instead of
+handing the file to `python3`.
+
 ## Runtime modes
 
 - **`wrap`** — the emulator executes the skill script directly (Python 3).

package/docs/QUICKSTART.md

@@ -10,12 +10,14 @@ kohala --version
 kohala doctor        # checks Node, Python, keys
 ```
 
-Requirements: Node.js ≥ 20 and Python 3 on your PATH.
+Requirements: Node.js ≥ 20. Python 3 is also required for Python agents.
 
 ## Create an agent
 
 ```bash
 kohala init my-agent
+# Or scaffold TypeScript:
+kohala init my-ts-agent --language ts
 ```
 
 This scaffolds:
@@ -29,6 +31,10 @@ my-agent/
     └── _tools.py      # the local tool SDK (stdlib-only, don't edit)
 ```
 
+The TypeScript scaffold uses `skills/main.ts` and `skills/_tools.ts`, and also
+includes a strict `tsconfig.json` plus `package.json` with its development
+dependencies declared.
+
 ## Run it
 
 ```bash
@@ -54,7 +60,7 @@ there.
 
 ## Iterate
 
-Edit `my-agent/skills/main.py` and `my-agent/kohala.json`, then run again.
+Edit `my-agent/skills/main.py` (or `main.ts`) and `my-agent/kohala.json`, then run again.
 Try removing a tool from `toolAllowlist` and watch the call fail loudly with
 `TOOL_DENIED` — that is exactly what the platform would do.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kohala/devkit",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Open-source CLI, local agent emulator, and open MCP memory server for Kohala agents. Build and run agents entirely on your own machine — then push the same agent to Kohala when you want it hosted.",
   "license": "MIT",
   "type": "module",
@@ -68,6 +68,7 @@
     "execa": "^9.6.1",
     "ora": "^9.4.1",
     "picocolors": "^1.1.1",
+    "tsx": "^4.21.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {

package/templates/python/README.md

@@ -0,0 +1,15 @@
+# {{AGENT_NAME}}
+
+A Python Kohala agent scaffolded by `kohala init`.
+
+## Commands
+
+```bash
+kohala validate {{AGENT_NAME}}
+kohala run {{AGENT_NAME}} --local
+kohala trace {{AGENT_NAME}}
+kohala deploy {{AGENT_NAME}} --dry-run
+```
+
+Run these from the directory containing the `{{AGENT_NAME}}/` folder. Edit
+`skills/main.py`; use `skills/_tools.py` for governed platform tool calls.

package/templates/python/kohala.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{AGENT_NAME}}",
+  "charter": "Collect one interesting fact per shift and store it in memory. Keep the output short and factual.",
+  "toolAllowlist": ["s3.put", "s3.get", "s3.list", "notify.send", "metrics.record"],
+  "runtimeMode": "wrap",
+  "skills": {
+    "main": "main.py"
+  },
+  "caps": {
+    "perRunTokens": 20000,
+    "perDayTokens": 100000
+  },
+  "validators": [
+    { "type": "shape", "minBytes": 10 },
+    { "type": "freshness", "asset": "{{AGENT_NAME}}/latest", "maxAgeHours": 24 }
+  ]
+}

package/templates/python/skills/_tools.py

@@ -0,0 +1,71 @@
+"""Kohala tool SDK. Uses the loopback runtime locally and hosted."""
+
+import json
+import os
+import urllib.request
+
+
+class KohalaToolError(Exception):
+    def __init__(self, code, message):
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+
+
+def _rpc(tool, args):
+    rpc_url = os.environ.get("KOHALA_RPC_URL")
+    if not rpc_url:
+        raise KohalaToolError("NO_RUNTIME", "KOHALA_RPC_URL is not set. Run via `kohala run <agent> --local`.")
+    request = urllib.request.Request(
+        rpc_url,
+        data=json.dumps({"tool": tool, "args": args}).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(request) as response:
+        body = json.loads(response.read().decode("utf-8"))
+    if not body.get("ok"):
+        error = body.get("error") or {}
+        raise KohalaToolError(error.get("code", "UNKNOWN"), error.get("message", "tool call failed"))
+    return body.get("result")
+
+
+def s3_put(key, body, category=None):
+    return _rpc("s3.put", {"key": key, "body": body, **({"category": category} if category is not None else {})})
+
+
+def s3_get(key_or_id):
+    return _rpc("s3.get", {"keyOrId": key_or_id})
+
+
+def s3_list(prefix=None, limit=None):
+    return _rpc("s3.list", {**({"prefix": prefix} if prefix is not None else {}), **({"limit": limit} if limit is not None else {})})
+
+
+def s3_delete(key_or_id):
+    return _rpc("s3.delete", {"keyOrId": key_or_id})
+
+
+def http_post_json(url, body, headers=None):
+    return _rpc("http.post_json", {"url": url, "body": body, **({"headers": headers} if headers is not None else {})})
+
+
+def llm_complete(prompt, model=None):
+    return _rpc("llm.complete", {"prompt": prompt, **({"model": model} if model is not None else {})})
+
+
+def notify_send(channel, message):
+    return _rpc("notify.send", {"channel": channel, "message": message})
+
+
+def metrics_record(name, value, tags=None):
+    return _rpc("metrics.record", {"name": name, "value": value, **({"tags": tags} if tags is not None else {})})
+
+
+def run_context():
+    return {
+        "agent": os.environ.get("KOHALA_AGENT", ""),
+        "run_id": os.environ.get("KOHALA_RUN_ID", ""),
+        "repair_attempt": int(os.environ.get("KOHALA_REPAIR_ATTEMPT", "0")),
+        "validator_feedback": os.environ.get("KOHALA_VALIDATOR_FEEDBACK", ""),
+    }

package/templates/python/skills/main.py

@@ -0,0 +1,25 @@
+"""{{AGENT_NAME}} — main skill."""
+
+import sys
+import time
+
+from _tools import s3_put, s3_list, notify_send, metrics_record, run_context
+
+
+def main():
+    context = run_context()
+    if context["repair_attempt"] > 0:
+        print(f"repair attempt {context['repair_attempt']}: {context['validator_feedback']}",
+              file=sys.stderr)
+
+    fact = f"Shift ran at {time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime())}."
+    s3_put("{{AGENT_NAME}}/latest", fact)
+    notify_send("dev", "shift completed")
+    metrics_record("facts_stored", 1)
+    existing = s3_list(prefix="{{AGENT_NAME}}/")
+    print(fact)
+    print(f"memory now holds {len(existing['records'])} asset(s) under '{{AGENT_NAME}}/'")
+
+
+if __name__ == "__main__":
+    main()

package/templates/typescript/README.md

@@ -0,0 +1,17 @@
+# {{AGENT_NAME}}
+
+A TypeScript Kohala agent scaffolded by `kohala init --language ts`.
+
+## Commands
+
+```bash
+npm install
+npm run typecheck
+kohala validate {{AGENT_NAME}}
+kohala run {{AGENT_NAME}} --local
+kohala deploy {{AGENT_NAME}} --dry-run
+```
+
+Run the Kohala commands from the directory containing the `{{AGENT_NAME}}/`
+folder. Edit `skills/main.ts`; use `skills/_tools.ts` for typed, governed
+platform tool calls. The same loopback RPC interface is available when hosted.

package/templates/typescript/kohala.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{AGENT_NAME}}",
+  "charter": "Collect one interesting fact per shift and store it in memory. Keep the output short and factual.",
+  "toolAllowlist": ["s3.put", "s3.get", "s3.list", "notify.send", "metrics.record"],
+  "runtimeMode": "wrap",
+  "skills": {
+    "main": "main.ts"
+  },
+  "dependencies": [],
+  "caps": {
+    "perRunTokens": 20000,
+    "perDayTokens": 100000
+  },
+  "validators": [
+    { "type": "shape", "minBytes": 10 },
+    { "type": "freshness", "asset": "{{AGENT_NAME}}/latest", "maxAgeHours": 24 }
+  ]
+}

package/templates/typescript/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "{{AGENT_NAME}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/typescript/skills/_tools.ts

@@ -0,0 +1,121 @@
+export class ToolError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(`${code}: ${message}`);
+    this.name = "ToolError";
+  }
+}
+
+interface RpcSuccess<T> {
+  ok: true;
+  result: T;
+}
+
+interface RpcFailure {
+  ok: false;
+  error?: { code?: string; message?: string };
+}
+
+export type ToolPayload = Record<string, unknown>;
+
+export interface ToolEnvelope<T = unknown> {
+  ok: boolean;
+  output?: T;
+  error?: string;
+  summary?: string;
+}
+
+export async function callToolRaw<T = unknown>(
+  toolId: string,
+  payload: ToolPayload,
+  _timeoutMs?: number,
+): Promise<ToolEnvelope<T>> {
+  const rpcUrl = process.env.KOHALA_RPC_URL;
+  if (!rpcUrl) {
+    throw new ToolError(
+      "NO_RUNTIME",
+      "KOHALA_RPC_URL is not set. Run via `kohala run <agent> --local`.",
+    );
+  }
+  const response = await fetch(rpcUrl, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ tool: toolId, args: payload }),
+  });
+  const body = (await response.json()) as RpcSuccess<T> | RpcFailure;
+  if (!body.ok) {
+    return {
+      ok: false,
+      error: `${body.error?.code ?? "UNKNOWN"}: ${body.error?.message ?? "tool call failed"}`,
+    };
+  }
+  return { ok: true, output: body.result };
+}
+
+export async function callTool<T = unknown>(
+  toolId: string,
+  payload: ToolPayload,
+  timeoutMs?: number,
+): Promise<T> {
+  const result = await callToolRaw<T>(toolId, payload, timeoutMs);
+  if (!result.ok) {
+    throw new ToolError("TOOL_ERROR", result.error ?? `${toolId}: tool returned ok=false`);
+  }
+  return result.output as T;
+}
+
+type ToolFunction<T = unknown> = (payload: ToolPayload, timeoutMs?: number) => Promise<T>;
+
+export interface KohalaTools {
+  [toolId: string]: ToolFunction;
+  s3Put: ToolFunction;
+  s3Get: ToolFunction;
+  s3List: ToolFunction<MemoryList>;
+  s3Delete: ToolFunction;
+  httpPostJson: ToolFunction;
+  llmComplete: ToolFunction<string>;
+  notifySend: ToolFunction;
+  metricsRecord: ToolFunction;
+}
+
+export const tools = new Proxy({} as KohalaTools, {
+  get: (_target, property) => {
+    const toolId = String(property).replace(/[A-Z]/g, (letter) => `.${letter.toLowerCase()}`);
+    return (payload: ToolPayload, timeoutMs?: number) => callTool(toolId, payload, timeoutMs);
+  },
+});
+
+export function configure(): never {
+  throw new ToolError(
+    "UNSUPPORTED",
+    "configure() is managed by the Kohala runtime and is unavailable locally.",
+  );
+}
+
+export const TOOL_IDS = [
+  "s3.put",
+  "s3.get",
+  "s3.list",
+  "s3.delete",
+  "http.post_json",
+  "llm.complete",
+  "notify.send",
+  "metrics.record",
+] as const;
+
+export function camel(id: string): string {
+  return id.replace(/[._-]+(.)/g, (_match, letter: string) => letter.toUpperCase());
+}
+
+export interface MemoryRecord {
+  id: string;
+  key: string;
+  [key: string]: unknown;
+}
+
+export interface MemoryList {
+  records: MemoryRecord[];
+  [key: string]: unknown;
+}

package/templates/typescript/skills/main.ts

@@ -0,0 +1,18 @@
+import { tools } from "./_tools.js";
+
+export async function run(): Promise<void> {
+  const fact = `Shift ran at ${new Date().toISOString()}.`;
+  await tools.s3Put({ key: "{{AGENT_NAME}}/latest", body: fact });
+  await tools.notifySend({ channel: "dev", message: "shift completed" });
+  await tools.metricsRecord({ name: "facts_stored", value: 1 });
+  const existing = await tools.s3List({ prefix: "{{AGENT_NAME}}/" });
+
+  console.log(fact);
+  console.log(`memory now holds ${existing.records.length} asset(s) under "{{AGENT_NAME}}/"`);
+}
+
+// The hosted Node lane imports and invokes `run`. The local emulator executes
+// this file directly and supplies KOHALA_RPC_URL.
+if (process.env.KOHALA_RPC_URL) {
+  await run();
+}

package/templates/typescript/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["skills/**/*.ts"]
+}

package/templates/README.md

@@ -1,40 +0,0 @@
-# {{AGENT_NAME}}
-
-A Kohala agent scaffolded by `kohala init`. Everything here runs on your own
-machine — no account, no billing, no waitlist.
-
-## Files
-
-- `kohala.json` — the agent manifest: charter, tools, caps, validators.
-- `skills/main.py` — the skill script. Its stdout is the run output.
-- `skills/_tools.py` — the local tool SDK (stdlib-only). Don't edit; it is the
-  same interface the hosted platform provides.
-
-## Commands
-
-```bash
-kohala validate {{AGENT_NAME}}      # check kohala.json
-kohala run {{AGENT_NAME}} --local   # run one shift with the local emulator
-kohala trace {{AGENT_NAME}}         # inspect the audit trail
-```
-
-Run these from the directory *containing* the `{{AGENT_NAME}}/` folder.
-
-## What the emulator enforces (exactly like the platform)
-
-1. **Admission** — refuses the shift if today's runs already hit `caps.perDayTokens`.
-2. **Tool allowlist** — every tool call is checked; anything not in
-   `toolAllowlist` fails with `TOOL_DENIED`.
-3. **Per-run cap** — LLM calls abort with `PER_RUN_TOKEN_CAP` before crossing
-   `caps.perRunTokens`.
-4. **Validators** — `shape`, `freshness`, and `invariant` checks run on the
-   output, with up to 2 repair attempts.
-
-Tokens are counted and shown in the trace, but nothing is ever billed locally.
-
-## Going live (optional)
-
-```bash
-kohala login                      # paste your pk_ key from kohala.ai
-kohala deploy {{AGENT_NAME}}      # idempotent; never deletes anything remotely
-```

package/templates/skills/_tools.py

@@ -1,125 +0,0 @@
-"""Kohala tool SDK (local twin).
-
-Your skill script talks to the Kohala runtime through these helpers. Locally
-they call the emulator over a loopback RPC endpoint; on the hosted platform
-the same functions talk to the real runtime. Your script does not change.
-
-Uses only the Python standard library — no pip installs needed.
-
-Available tools (each must also be listed in kohala.json -> toolAllowlist):
-
-    s3_put(key, body, category=None)   store text in agent memory
-    s3_get(key_or_id)                  fetch a memory asset
-    s3_list(prefix=None, limit=None)   list active memory assets
-    s3_delete(key_or_id)               remove + deactivate an asset
-    http_post_json(url, body, headers=None)  POST JSON to an external API
-    llm_complete(prompt, model=None)   complete text with YOUR OWN LLM key
-    notify_send(channel, message)      send a notification (trace, locally)
-    metrics_record(name, value, tags=None)   record a metric (trace, locally)
-
-Every helper raises KohalaToolError on failure — including TOOL_DENIED when
-the tool is not in your allowlist, and PER_RUN_TOKEN_CAP when an LLM call
-would cross your per-run token cap. Errors are loud on purpose.
-"""
-
-import json
-import os
-import urllib.request
-
-
-class KohalaToolError(Exception):
-    """A tool call failed. `code` is the platform's machine-readable code."""
-
-    def __init__(self, code, message):
-        super().__init__(f"{code}: {message}")
-        self.code = code
-        self.message = message
-
-
-def _rpc(tool, args):
-    rpc_url = os.environ.get("KOHALA_RPC_URL")
-    if not rpc_url:
-        raise KohalaToolError(
-            "NO_RUNTIME",
-            "KOHALA_RPC_URL is not set. Run this script via `kohala run <agent> --local`, "
-            "not directly with python.",
-        )
-    payload = json.dumps({"tool": tool, "args": args}).encode("utf-8")
-    request = urllib.request.Request(
-        rpc_url,
-        data=payload,
-        headers={"Content-Type": "application/json"},
-        method="POST",
-    )
-    with urllib.request.urlopen(request) as response:
-        body = json.loads(response.read().decode("utf-8"))
-    if not body.get("ok"):
-        error = body.get("error") or {}
-        raise KohalaToolError(error.get("code", "UNKNOWN"), error.get("message", "tool call failed"))
-    return body.get("result")
-
-
-def s3_put(key, body, category=None):
-    args = {"key": key, "body": body}
-    if category is not None:
-        args["category"] = category
-    return _rpc("s3.put", args)
-
-
-def s3_get(key_or_id):
-    return _rpc("s3.get", {"keyOrId": key_or_id})
-
-
-def s3_list(prefix=None, limit=None):
-    args = {}
-    if prefix is not None:
-        args["prefix"] = prefix
-    if limit is not None:
-        args["limit"] = limit
-    return _rpc("s3.list", args)
-
-
-def s3_delete(key_or_id):
-    return _rpc("s3.delete", {"keyOrId": key_or_id})
-
-
-def http_post_json(url, body, headers=None):
-    args = {"url": url, "body": body}
-    if headers is not None:
-        args["headers"] = headers
-    return _rpc("http.post_json", args)
-
-
-def llm_complete(prompt, model=None):
-    args = {"prompt": prompt}
-    if model is not None:
-        args["model"] = model
-    return _rpc("llm.complete", args)
-
-
-def notify_send(channel, message):
-    return _rpc("notify.send", {"channel": channel, "message": message})
-
-
-def metrics_record(name, value, tags=None):
-    args = {"name": name, "value": value}
-    if tags is not None:
-        args["tags"] = tags
-    return _rpc("metrics.record", args)
-
-
-def run_context():
-    """Info about the current shift, including repair-loop state.
-
-    Returns a dict with:
-      agent            the agent name
-      run_id           unique id of this shift
-      repair_attempt   0 on the first try, 1..2 on repair attempts
-      validator_feedback  why validators failed last attempt (empty on first try)
-    """
-    return {
-        "agent": os.environ.get("KOHALA_AGENT", ""),
-        "run_id": os.environ.get("KOHALA_RUN_ID", ""),
-        "repair_attempt": int(os.environ.get("KOHALA_REPAIR_ATTEMPT", "0")),
-        "validator_feedback": os.environ.get("KOHALA_VALIDATOR_FEEDBACK", ""),
-    }