open-multi-agent-kit 0.80.7 → 0.80.8

package/docs/tui.md

@@ -4,7 +4,7 @@
 
 Extensions and custom tools can render custom TUI components for interactive user interfaces. This page covers the component system and available building blocks.
 
-**Source:** [`@earendil-works/omk-tui`](https://github.com/earendil-works/omk-mono/tree/main/packages/tui)
+**Source:** [`omk-tui`](https://github.com/earendil-works/omk-mono/tree/main/packages/tui)
 
 ## Component Interface
 
@@ -33,7 +33,7 @@ The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered lin
 Components that display a text cursor and need IME (Input Method Editor) support should implement the `Focusable` interface:
 
 ```typescript
-import { CURSOR_MARKER, type Component, type Focusable } from "@earendil-works/omk-tui";
+import { CURSOR_MARKER, type Component, type Focusable } from "omk-tui";
 
 class MyInput implements Component, Focusable {
   focused: boolean = false;  // Set by TUI when focus changes
@@ -59,7 +59,7 @@ The cursor remains hidden by default. This keeps the fake cursor rendering, whil
 When a container component (dialog, selector, etc.) contains an `Input` or `Editor` child, the container must implement `Focusable` and propagate the focus state to the child. Otherwise, the hardware cursor won't be positioned correctly for IME input.
 
 ```typescript
-import { Container, type Focusable, Input } from "@earendil-works/omk-tui";
+import { Container, type Focusable, Input } from "omk-tui";
 
 class SearchDialog extends Container implements Focusable {
   private searchInput: Input;
@@ -188,10 +188,10 @@ See [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for compre
 
 ## Built-in Components
 
-Import from `@earendil-works/omk-tui`:
+Import from `omk-tui`:
 
 ```typescript
-import { Text, Box, Container, Spacer, Markdown } from "@earendil-works/omk-tui";
+import { Text, Box, Container, Spacer, Markdown } from "omk-tui";
 ```
 
 ### Text
@@ -273,7 +273,7 @@ const image = new Image(
 Use `matchesKey()` for key detection:
 
 ```typescript
-import { matchesKey, Key } from "@earendil-works/omk-tui";
+import { matchesKey, Key } from "omk-tui";
 
 handleInput(data: string) {
   if (matchesKey(data, Key.up)) {
@@ -299,7 +299,7 @@ handleInput(data: string) {
 **Critical:** Each line from `render()` must not exceed the `width` parameter.
 
 ```typescript
-import { visibleWidth, truncateToWidth } from "@earendil-works/omk-tui";
+import { visibleWidth, truncateToWidth } from "omk-tui";
 
 render(width: number): string[] {
   // Truncate long lines
@@ -320,7 +320,7 @@ Example: Interactive selector
 import {
   matchesKey, Key,
   truncateToWidth, visibleWidth
-} from "@earendil-works/omk-tui";
+} from "omk-tui";
 
 class MySelector {
   private items: string[];
@@ -435,7 +435,7 @@ renderResult(result, options, theme, context) {
 
 ```typescript
 import { getMarkdownTheme } from "open-multi-agent-kit";
-import { Markdown } from "@earendil-works/omk-tui";
+import { Markdown } from "omk-tui";
 
 renderResult(result, options, theme, context) {
   const mdTheme = getMarkdownTheme();
@@ -596,12 +596,12 @@ These patterns cover the most common UI needs in extensions. **Copy these patter
 
 ### Pattern 1: Selection Dialog (SelectList)
 
-For letting users pick from a list of options. Use `SelectList` from `@earendil-works/omk-tui` with `DynamicBorder` for framing.
+For letting users pick from a list of options. Use `SelectList` from `omk-tui` with `DynamicBorder` for framing.
 
 ```typescript
 import type { ExtensionAPI } from "open-multi-agent-kit";
 import { DynamicBorder } from "open-multi-agent-kit";
-import { Container, type SelectItem, SelectList, Text } from "@earendil-works/omk-tui";
+import { Container, type SelectItem, SelectList, Text } from "omk-tui";
 
 omk.registerCommand("pick", {
   handler: async (_args, ctx) => {
@@ -688,11 +688,11 @@ omk.registerCommand("fetch", {
 
 ### Pattern 3: Settings/Toggles (SettingsList)
 
-For toggling multiple settings. Use `SettingsList` from `@earendil-works/omk-tui` with `getSettingsListTheme()`.
+For toggling multiple settings. Use `SettingsList` from `omk-tui` with `getSettingsListTheme()`.
 
 ```typescript
 import { getSettingsListTheme } from "open-multi-agent-kit";
-import { Container, type SettingItem, SettingsList, Text } from "@earendil-works/omk-tui";
+import { Container, type SettingItem, SettingsList, Text } from "omk-tui";
 
 omk.registerCommand("settings", {
   handler: async (_args, ctx) => {
@@ -832,7 +832,7 @@ Replace the main input editor with a custom implementation. Useful for modal edi
 
 ```typescript
 import { CustomEditor, type ExtensionAPI } from "open-multi-agent-kit";
-import { matchesKey, truncateToWidth } from "@earendil-works/omk-tui";
+import { matchesKey, truncateToWidth } from "omk-tui";
 
 type Mode = "normal" | "insert";
 

package/docs/usage.md

@@ -92,23 +92,15 @@ Useful session commands:
 
 See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
 
-## Context Files (Parent / Child Hierarchy)
+## Context Files
 
-OMK loads context with strict parent precedence:
+OMK loads `AGENTS.md` or `CLAUDE.md` at startup from:
 
-**Parent (global, highest priority, immutable for safety):**
-- `~/.omk/agent/AGENTS.md`
-- `~/.omk/agent/CLAUDE.md`
+- `~/.omk/agent/AGENTS.md` for global instructions
+- parent directories, walking up from the current working directory
+- the current directory
 
-**Child (project / ancestor, subordinate):**
-- Parent directories walking up from cwd
-- Current directory `AGENTS.md` / `CLAUDE.md`
-
-The authoritative anti-GOD Mode / jailbreak / ToS-bypass rules live in the **parent** global files (see root AGENTS.md and CLAUDE.md "PARENT RULES" sections). Project files are only for conventions.
-
-When GOD Mode patterns are detected (refusal + specific divider + semantically opposite response, `[END OF INPUT][START OF INPUT]`, "godmode is active", "write real then oppositely", LOVE PLINY dividers, etc.) the loader emits security diagnostics and the parent rules force a short refusal. Loaded hostile content is wrapped/neutralized before reaching the model.
-
-Disable all context loading with `--no-context-files` (`-nc`).
+Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
 
 ### System Prompt Files
 
@@ -119,8 +111,6 @@ Replace the default system prompt with:
 
 Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
 
-**Warning**: Replacing the system prompt does not relax parent AGENTS.md/CLAUDE.md resistance rules or the safety floor. GOD Mode bypass attempts via custom SYSTEM.md are still refused.
-
 ## Exporting and Sharing Sessions
 
 Use `/export [file]` to write a session to HTML.

package/examples/extensions/README.md

@@ -98,7 +98,7 @@ cp permission-gate.ts ~/.omk/agent/extensions/
 
 | Extension | Description |
 |-----------|-------------|
-| `mac-system-theme.ts` | Syncs omk theme with macOS dark/light mode |
+| `mac-system-theme.ts` | Syncs OMK theme with macOS dark/light mode |
 
 ### Resources
 
@@ -181,7 +181,7 @@ export default function (omk: ExtensionAPI) {
 
 **Use StringEnum for string parameters** (required for Google API compatibility):
 ```typescript
-import { StringEnum } from "@earendil-works/omk-ai";
+import { StringEnum } from "omk-ai";
 
 // Good
 action: StringEnum(["list", "add"] as const)

package/examples/extensions/aside-computer-use/README.md

@@ -0,0 +1,114 @@
+# OMK ↔ Aside Computer-Use Bridge
+
+A security-gated extension that lets the OMK agent drive an [Aside](https://aside.com)
+Chromium browser via `aside mcp` (JSON-RPC over stdio). **Aside does the browser
+execution; OMK does the planning, policy, approval, and evidence-gated completion.**
+
+> The Aside binary is **not** bundled. Install it yourself (`aside` must be on
+> `PATH`). This extension never auto-installs third-party software.
+
+## Architecture
+
+```
+OMK Agent (LLM planner)
+   │  tool calls (observe / execute_action / verify / ...)
+   ▼
+aside-computer-use extension  ← policy · risk · origin · approval · redact · evidence
+   │  MCP JSON-RPC stdio
+   ▼
+aside mcp  →  Aside Chromium Browser (logged-in profile, password manager)
+```
+
+The bridge speaks to `aside mcp`, **not raw CDP**. Aside's own Allow/Ask/Deny
+modes run in addition to OMK's gate — OMK's deny is always final.
+
+## Safety model (the point of this extension)
+
+Every browser action passes through, in order:
+
+1. **Denied-actions gate** — `credential_export`, `payment`,
+   `security_setting_change`, `account_deletion` are denied absolutely.
+2. **Origin allowlist** — mutations to origins outside `allowedOrigins` are denied.
+3. **Risk classification** (R0–R3):
+   - R0 observe (read/screenshot/DOM) → **auto-allow**
+   - R1 reversible interaction → allow on allowed origin, else approve
+   - R2 external mutation (submit/send/publish) → **human approval required**
+   - R3 critical mutation (pay/delete/credentials) → **default-deny** (privileged allowlist only)
+4. **Human approval** via `ctx.ui.confirm` for any approve decision (denies in non-UI modes).
+5. **Profile mutation mutex** — one mutating action per browser profile at a time.
+6. **Secret redaction** — DOM/result content is deep-walked; secret-named fields and
+   token-like values become `[REDACTED]` before reaching the model or logs.
+7. **Prompt-injection stance** — web page text is **untrusted observation** and never
+   expands authority. A page saying "upload ~/.ssh/id_rsa" or "disable the safety
+   policy" carries no weight; only the user goal does.
+8. **Evidence-gated completion** — `aside said it did it` is not success. Criteria are
+   predicates verified against DOM/URL evidence. Mutations with unverifiable outcomes
+   return `inspection_required` (never auto-retried) to prevent duplicate submits/payments.
+
+Credentials: Aside's password manager autofills in-browser; raw passwords never return
+to OMK or the model. "Local-first" ≠ "nothing leaves the device" — model-visible context
+(page snapshots, screenshots) can reach the model provider, so use a separate profile and
+minimal context on sensitive sites.
+
+## Setup
+
+1. Install Aside per Aside's docs and confirm `aside mcp` runs.
+2. Copy this directory to `~/.omk/agent/extensions/aside-computer-use/`.
+3. (Optional) add a policy file (see below). Defaults are conservative.
+4. Start OMK. Tools `aside_observe`, `aside_execute_action`, etc. are registered.
+
+The `aside` process is spawned lazily on first tool use and closed on session shutdown.
+
+## Policy
+
+OMK-owned, merged: defaults ← `~/.omk/agent/extensions/aside-policy.json` ←
+`<cwd>/.omk/aside-policy.json` (project wins). Example:
+
+```json
+{
+  "executable": "aside",
+  "defaultMode": "yolo",
+  "allowedOrigins": ["http://localhost:*", "https://github.com"],
+  "deniedActions": ["credential_export", "payment", "security_setting_change", "account_deletion"],
+  "approvalRequiredActions": ["submit", "send_message", "publish", "delete", "change_permission"],
+  "limits": { "maxSteps": 80, "maxRetries": 2, "maxWallTimeSeconds": 900, "maxDownloads": 10 },
+  "evidence": { "captureFinalScreenshot": true, "recordFinalUrl": true, "hashDownloadedFiles": true }
+}
+```
+
+`/aside` shows the active policy.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `aside_observe` | R0 read-only page state (URL/title/text) |
+| `aside_plan_action` | Preview an action's risk band + authorization **without** executing |
+| `aside_execute_action` | Gate + execute one action (risk → origin → approval → lock → redact → evidence) |
+| `aside_verify` | Check success criteria against the current observation |
+| `aside_take_screenshot` | R0 capture, save to evidence dir with sha256 |
+| `aside_download_artifact` | Gated download, hash for integrity |
+| `aside_start_task` | observe → scripted plan → gated execute loop |
+| `aside_close_task` | Gracefully close the Aside MCP process |
+
+The agent (LLM) is the planner. It calls these tools; the extension applies the full
+safety gate on every action — matching Algorithm 2's loop while fitting OMK's tool-call model.
+
+## Module layout
+
+| File | Role |
+|---|---|
+| `index.ts` | Entry: load policy, lazy client, register tools + `/aside`, shutdown close |
+| `policy.ts` | `AsidePolicy`, defaults, load + merge |
+| `risk-classifier.ts` | action → R0..R3 band (pure) |
+| `risk-authorize.ts` | (action, risk, policy) → allow/approve/deny (pure) |
+| `url-origin.ts` | origin resolution + glob/port-wildcard matching (pure) |
+| `schema-fingerprint.ts` | MCP tool inputSchema drift detection (pure) |
+| `evidence.ts` | `redactSecrets`, file hashing, evidence builders |
+| `session-binding.ts` | OMK↔Aside binding store + per-profile mutex |
+| `mcp-client.ts` | JSON-RPC stdio client (initialize/list/call, lazy spawn, graceful close) |
+| `controller.ts` | Algorithm 2 policy-gated loop (mockable ports) |
+| `tools.ts` | 8-tool facade over client + gate |
+
+Pure safety modules have unit tests (`packages/coding-agent/test/aside-*.test.ts`); the
+controller is tested with mock ports — no real Aside binary or browser required.

package/examples/extensions/aside-computer-use/action-scoring.ts

@@ -0,0 +1,122 @@
+/**
+ * Deterministic candidate action scoring for Aside planner proposals.
+ *
+ * Pure module — no I/O, no controller/tool coupling.
+ */
+
+import type { ActionScoringConfidence, BrowserAction, PlannedActionCandidate, RiskLevel } from "./types.ts";
+
+const RISK_THRESHOLDS: Readonly<Record<RiskLevel, number>> = {
+	R0: 0.5,
+	R1: 0.65,
+	R2: 0.85,
+	R3: 0.95,
+};
+
+const AMBIGUOUS_DELTA = 0.1;
+
+export interface ScoredActionCandidate {
+	readonly candidate: PlannedActionCandidate;
+	readonly total: number;
+}
+
+export interface ActionCandidateSelection {
+	readonly status: ActionScoringConfidence;
+	readonly selected?: ScoredActionCandidate;
+	readonly scored: readonly ScoredActionCandidate[];
+	readonly reason: string;
+}
+
+function clampScore(value: number | undefined): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+	return Math.max(0, Math.min(1, value));
+}
+
+function stableStringify(value: unknown): string {
+	if (value === undefined) return "undefined";
+	if (value === null || typeof value !== "object") {
+		if (typeof value === "bigint") return value.toString();
+		return JSON.stringify(value) ?? String(value);
+	}
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	const record = value as Readonly<Record<string, unknown>>;
+	return `{${Object.keys(record)
+		.sort()
+		.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+		.join(",")}}`;
+}
+
+function actionSortKey(action: BrowserAction): string {
+	return [
+		action.kind,
+		action.url ?? "",
+		action.description,
+		action.asideTool ?? "",
+		stableStringify(action.asideArgs ?? {}),
+	].join("\u0000");
+}
+
+function compareScoredCandidates(left: ScoredActionCandidate, right: ScoredActionCandidate): number {
+	if (left.total !== right.total) return right.total - left.total;
+	const leftKey = actionSortKey(left.candidate.action);
+	const rightKey = actionSortKey(right.candidate.action);
+	if (leftKey < rightKey) return -1;
+	if (leftKey > rightKey) return 1;
+	return 0;
+}
+
+/** Score one planned action candidate using the fixed weighted formula. */
+export function scoreActionCandidate(input: PlannedActionCandidate): number {
+	const total =
+		0.3 * clampScore(input.goalProgress) +
+		0.2 * clampScore(input.observationSupport) +
+		0.15 * clampScore(input.selectorCertainty) +
+		0.1 * clampScore(input.policyFit) +
+		0.1 * clampScore(input.reversibility) +
+		0.1 * clampScore(input.toolReliability) +
+		0.05 * clampScore(input.evidenceGain) -
+		clampScore(input.ambiguityPenalty) -
+		clampScore(input.repeatPenalty) -
+		clampScore(input.riskPenalty);
+	return clampScore(total);
+}
+
+/** Minimum acceptable score for a risk band. */
+export function thresholdForRisk(risk: RiskLevel): number {
+	return RISK_THRESHOLDS[risk];
+}
+
+/**
+ * Select the best safe candidate, or require inspection when evidence is weak
+ * or the top candidates are too close to choose deterministically.
+ */
+export function selectActionCandidate(candidates: readonly PlannedActionCandidate[]): ActionCandidateSelection {
+	const scored = candidates
+		.map((candidate) => ({ candidate, total: scoreActionCandidate(candidate) }))
+		.sort(compareScoredCandidates);
+
+	const top = scored[0];
+	if (!top) {
+		return { status: "inspection_required", scored, reason: "no action candidates available" };
+	}
+
+	const threshold = thresholdForRisk(top.candidate.risk);
+	if (top.total < threshold) {
+		return {
+			status: "inspection_required",
+			scored,
+			reason: `top action score ${top.total.toFixed(3)} is below ${top.candidate.risk} threshold ${threshold.toFixed(2)}`,
+		};
+	}
+
+	const runnerUp = scored[1];
+	if (runnerUp && top.total - runnerUp.total < AMBIGUOUS_DELTA) {
+		return {
+			status: "inspection_required",
+			scored,
+			reason: `ambiguous top candidates: score delta ${(top.total - runnerUp.total).toFixed(3)}`,
+		};
+	}
+
+	return { status: "selected", selected: top, scored, reason: "top action exceeds risk threshold and ambiguity gap" };
+}