@burtson-labs/host-kit 0.3.1

package/dist/permissions.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Permission policy for tool execution.
+ *
+ * Hosts (CLI, VS Code extension) consult the policy BEFORE a tool runs.
+ * The policy returns one of:
+ *   - 'allow' : proceed without prompting
+ *   - 'ask'   : prompt the user (host decides how — modal, [y/N], etc.)
+ *   - 'deny'  : abort, model sees a blocked-tool result
+ *
+ * Patterns can target a tool by name ("write_file") or a tool+arg filter
+ * ("write_file:src/**", "run_command:npm test*"). Glob matching uses the
+ * same minimal engine as host-kit/mentions — *, **, ?, and {a,b}.
+ *
+ * Config shape in .bandit/settings.json:
+ *
+ *   {
+ *     "permissions": {
+ *       "allow": ["read_file", "list_files", "search_code", "write_file:docs/**"],
+ *       "deny":  ["run_command:rm *"],
+ *       "ask":   ["write_file", "run_command"]
+ *     }
+ *   }
+ *
+ * Evaluation order: deny > allow > ask > default.
+ * Default for dangerous tools (write_file, apply_edit, replace_range, run_command) is 'ask'.
+ * Default for read-only tools is 'allow'.
+ */
+export type PermissionDecision = 'allow' | 'ask' | 'deny';
+export interface PermissionPolicy {
+    allow: string[];
+    deny: string[];
+    ask: string[];
+}
+export declare const emptyPolicy: () => PermissionPolicy;
+/**
+ * Merge two policies. Used to combine workspace settings with session
+ * overrides (e.g. the user's "always allow for this session" choices).
+ */
+export declare function mergePolicies(a: PermissionPolicy, b: PermissionPolicy): PermissionPolicy;
+/**
+ * Evaluate the policy for a tool invocation. Returns the decision.
+ *
+ * @param toolName     Tool being invoked (e.g. "write_file")
+ * @param primary      The first meaningful param value (path, cmd, url…)
+ *                     used for fine-grained pattern matching. Empty
+ *                     string if unknown.
+ * @param policy       Merged workspace + session policy.
+ * @param primaryFull  Optional fuller representation of the invocation
+ *                     used for pattern matching alongside `primary`.
+ *                     For `run_command` the host should pass the full
+ *                     command line ("git push origin main") so glob
+ *                     patterns like `run_command:git *` and
+ *                     `run_command:rm *` work intuitively. When
+ *                     omitted (default) only `primary` is consulted —
+ *                     preserves the original semantics for callers
+ *                     that don't need the wider match.
+ */
+export declare function evaluatePermission(toolName: string, primary: string, policy: PermissionPolicy, primaryFull?: string): PermissionDecision;
+/**
+ * In-memory store for session-level "always allow" choices. Hosts instantiate
+ * one per conversation so approvals reset when the user starts fresh.
+ */
+export declare class SessionPermissionStore {
+    private readonly allow;
+    /** Remember an "always allow for this session" choice. */
+    grant(toolName: string, primary?: string): void;
+    /** Returns a policy fragment reflecting session grants only. */
+    toPolicy(): PermissionPolicy;
+    clear(): void;
+    size(): number;
+}
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AA0FD,eAAO,MAAM,WAAW,QAAO,gBAAsD,CAAC;AAEtF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAMxF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,gBAAgB,EACxB,WAAW,CAAC,EAAE,MAAM,GACnB,kBAAkB,CAepB;AA2ED;;;GAGG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAE3C,0DAA0D;IAC1D,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI/C,gEAAgE;IAChE,QAAQ,IAAI,gBAAgB;IAI5B,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,MAAM;CAGf"}

package/dist/permissions.js

@@ -0,0 +1,271 @@
+"use strict";
+/**
+ * Permission policy for tool execution.
+ *
+ * Hosts (CLI, VS Code extension) consult the policy BEFORE a tool runs.
+ * The policy returns one of:
+ *   - 'allow' : proceed without prompting
+ *   - 'ask'   : prompt the user (host decides how — modal, [y/N], etc.)
+ *   - 'deny'  : abort, model sees a blocked-tool result
+ *
+ * Patterns can target a tool by name ("write_file") or a tool+arg filter
+ * ("write_file:src/**", "run_command:npm test*"). Glob matching uses the
+ * same minimal engine as host-kit/mentions — *, **, ?, and {a,b}.
+ *
+ * Config shape in .bandit/settings.json:
+ *
+ *   {
+ *     "permissions": {
+ *       "allow": ["read_file", "list_files", "search_code", "write_file:docs/**"],
+ *       "deny":  ["run_command:rm *"],
+ *       "ask":   ["write_file", "run_command"]
+ *     }
+ *   }
+ *
+ * Evaluation order: deny > allow > ask > default.
+ * Default for dangerous tools (write_file, apply_edit, replace_range, run_command) is 'ask'.
+ * Default for read-only tools is 'allow'.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionPermissionStore = exports.emptyPolicy = void 0;
+exports.mergePolicies = mergePolicies;
+exports.evaluatePermission = evaluatePermission;
+/** Tools that mutate state or execute code and therefore require ask-by-default. */
+const DANGEROUS_TOOLS = new Set(['write_file', 'apply_edit', 'replace_range', 'apply_patch', 'run_command']);
+/**
+ * Mutating-tool name patterns used to gate MCP-bridged tools that
+ * aren't in the static DANGEROUS_TOOLS set. Catches tools whose names
+ * imply they change state outside Bandit's process — Gmail filters,
+ * Calendar events, Drive files, etc. — so the user sees a permission
+ * card before the agent silently archives 200 emails or creates a
+ * filter that auto-trashes mail.
+ *
+ * Captured 2026-05-25: bandit-logic ran createFilter +
+ * modifyMessageLabels + trashMessage without any permission prompt
+ * because they're all MCP-bridged tools and the evaluator defaulted
+ * to 'allow' for anything not in DANGEROUS_TOOLS. The user had no
+ * idea the inbox was being changed until after the fact.
+ *
+ * Read-only patterns (list*, get*, search*, read*) are deliberately
+ * NOT in this list — auto-allowing those keeps the agent able to
+ * browse without prompt-spam. The principle: ask before write,
+ * allow read by default.
+ */
+const MUTATING_PATTERNS = [
+    /^create[A-Z_]/, // createFilter, createLabel, createEvent, createFolder, create_event
+    /^update[A-Z_]/, // updateDraft, updateEvent, updateSpreadsheet
+    /^modify[A-Z_]/, // modifyMessageLabels, modify_message_labels
+    /^delete[A-Z_]/, // deleteEvent, deleteFile, deleteFilter
+    /^remove[A-Z_]/, // removeLabel, removeMember
+    /^trash[A-Z_]/, // trashMessage
+    /^archive[A-Z_]/, // archiveMessage
+    /^move[A-Z_]/, // moveFile, moveMessage
+    /^send[A-Z_]/, // sendEmail, sendDraft, sendMessage
+    /^post[A-Z_]/, // postMessage, postComment
+    /^add[A-Z_]/, // addComment, addMember (catches additive mutations too)
+    /^insert[A-Z_]/, // insertText, insertEvent
+    /^replace[A-Z_]/, // replaceTableRowData, findAndReplace
+    /^rename[A-Z_]/, // renameSheet, renameTab, renameFile
+    /^duplicate[A-Z_]/, // duplicateSheet
+    /^batch[A-Z_]/, // batchWrite, batchUpdate
+    /^write[A-Z_]/, // writeSpreadsheet
+    /^append[A-Z_]/, // appendTableRows, appendToGoogleDoc, appendSpreadsheetRows
+    /^clear[A-Z_]/, // clearSpreadsheetRange
+    /^copy[A-Z_]/, // copyFile, copySheetTo (creates a new resource)
+    /^upload[A-Z_]/, // uploadFile
+    /^revoke[A-Z_]/, // revokeAccess
+    /^grant[A-Z_]/, // grantPermission
+    /^triage[A-Z_]/, // triageInbox (writes label/state)
+    /^apply[A-Z_]/, // applyTextStyle, applyParagraphStyle (modifies docs)
+    /^set[A-Z_]/, // setCellBorders, setRowHeights, setColumnWidths
+    /^protect[A-Z_]/, // protectRange
+    /^group[A-Z_]/, // groupRows
+    /^ungroup[A-Z_]/, // ungroupAllRows
+    /^freeze[A-Z_]/, // freezeRowsAndColumns
+    /^auto[Rr]esize/, // autoResizeColumns / autoResizeRows
+    /^reply[A-Z_]/, // replyToComment, replyToSheetsComment
+    /^cancel[A-Z_]/, // cancelEvent
+    /^quick[Aa]dd/, // quickAddEvent
+];
+/**
+ * Strip the MCP namespace prefix (e.g. "burtson-labs.createFilter" →
+ * "createFilter") before pattern-testing. Tools registered via
+ * mcpToolToAgentTool get a "<server>.<tool>" naming convention; the
+ * mutating-verb test operates on the tool name itself.
+ */
+function stripMcpNamespace(toolName) {
+    const dotIdx = toolName.indexOf('.');
+    if (dotIdx > 0)
+        return toolName.slice(dotIdx + 1);
+    // mcp__server__tool naming convention (alternate)
+    const underIdx = toolName.indexOf('__');
+    if (underIdx > 0 && toolName.startsWith('mcp__')) {
+        const after = toolName.slice(underIdx + 2);
+        const next = after.indexOf('__');
+        return next > 0 ? after.slice(next + 2) : after;
+    }
+    return toolName;
+}
+/**
+ * Does this tool's name look like a mutating operation?
+ * Used as the default-ask gate for MCP-bridged tools that aren't
+ * declared in the in-tree DANGEROUS_TOOLS set.
+ */
+function looksMutating(toolName) {
+    const bareName = stripMcpNamespace(toolName);
+    return MUTATING_PATTERNS.some((re) => re.test(bareName));
+}
+const emptyPolicy = () => ({ allow: [], deny: [], ask: [] });
+exports.emptyPolicy = emptyPolicy;
+/**
+ * Merge two policies. Used to combine workspace settings with session
+ * overrides (e.g. the user's "always allow for this session" choices).
+ */
+function mergePolicies(a, b) {
+    return {
+        allow: [...new Set([...a.allow, ...b.allow])],
+        deny: [...new Set([...a.deny, ...b.deny])],
+        ask: [...new Set([...a.ask, ...b.ask])]
+    };
+}
+/**
+ * Evaluate the policy for a tool invocation. Returns the decision.
+ *
+ * @param toolName     Tool being invoked (e.g. "write_file")
+ * @param primary      The first meaningful param value (path, cmd, url…)
+ *                     used for fine-grained pattern matching. Empty
+ *                     string if unknown.
+ * @param policy       Merged workspace + session policy.
+ * @param primaryFull  Optional fuller representation of the invocation
+ *                     used for pattern matching alongside `primary`.
+ *                     For `run_command` the host should pass the full
+ *                     command line ("git push origin main") so glob
+ *                     patterns like `run_command:git *` and
+ *                     `run_command:rm *` work intuitively. When
+ *                     omitted (default) only `primary` is consulted —
+ *                     preserves the original semantics for callers
+ *                     that don't need the wider match.
+ */
+function evaluatePermission(toolName, primary, policy, primaryFull) {
+    // Deny has highest precedence — explicit deny wins over explicit allow.
+    if (matchesAny(toolName, primary, policy.deny, primaryFull))
+        return 'deny';
+    if (matchesAny(toolName, primary, policy.allow, primaryFull))
+        return 'allow';
+    if (matchesAny(toolName, primary, policy.ask, primaryFull))
+        return 'ask';
+    // Default: dangerous tools require explicit permission, read-only are OK.
+    // MCP-bridged tools whose names imply they mutate external state
+    // (createFilter, trashMessage, modifyMessageLabels, sendEmail, etc.)
+    // also default to 'ask' — without this, every MCP tool gets auto-
+    // allowed and the user has no chance to stop the agent before it
+    // archives 200 emails or creates a forwarding rule.
+    if (DANGEROUS_TOOLS.has(toolName))
+        return 'ask';
+    if (looksMutating(toolName))
+        return 'ask';
+    return 'allow';
+}
+function matchesAny(toolName, primary, patterns, primaryFull) {
+    for (const raw of patterns) {
+        const pattern = raw.trim();
+        if (!pattern)
+            continue;
+        const colon = pattern.indexOf(':');
+        if (colon === -1) {
+            // Tool-only pattern: matches every invocation of that tool.
+            if (pattern === toolName)
+                return true;
+            continue;
+        }
+        const toolPart = pattern.slice(0, colon);
+        const argPart = pattern.slice(colon + 1);
+        if (toolPart !== toolName)
+            continue;
+        // Try the wider form first when provided — this is what makes
+        // patterns like `run_command:git *` and `run_command:rm *` work
+        // (matching against "git push origin main", not just "git"). Fall
+        // back to the narrow primary for grants stored at binary-only
+        // scope and for non-run_command tools where primaryFull is
+        // identical to primary.
+        if (primaryFull && globMatch(argPart, primaryFull))
+            return true;
+        if (globMatch(argPart, primary))
+            return true;
+    }
+    return false;
+}
+/**
+ * Permission-pattern glob matcher.
+ *
+ * Unlike path-glob matchers, this one treats `*` as greedy (matching slashes
+ * too) because permission patterns target heterogeneous inputs (commands,
+ * URLs, paths) and users don't expect `/` to be segmenting. Keep `**` as an
+ * alias for `*` for user convenience so both "write_file:src/**" and
+ * "run_command:rm *" behave intuitively.
+ */
+function globMatch(pattern, input) {
+    const regex = globToRegex(pattern);
+    return regex.test(input);
+}
+function globToRegex(glob) {
+    let out = '^';
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === '*') {
+            if (glob[i + 1] === '*') {
+                i++;
+            }
+            out += '.*';
+        }
+        else if (ch === '?') {
+            out += '.';
+        }
+        else if (ch === '{') {
+            const end = glob.indexOf('}', i);
+            if (end === -1) {
+                out += '\\{';
+                continue;
+            }
+            const opts = glob.slice(i + 1, end).split(',').map(escapeRegex).join('|');
+            out += `(?:${opts})`;
+            i = end;
+        }
+        else if (/[.+^$()|\\]/.test(ch)) {
+            out += '\\' + ch;
+        }
+        else {
+            out += ch;
+        }
+    }
+    out += '$';
+    return new RegExp(out);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * In-memory store for session-level "always allow" choices. Hosts instantiate
+ * one per conversation so approvals reset when the user starts fresh.
+ */
+class SessionPermissionStore {
+    constructor() {
+        this.allow = new Set();
+    }
+    /** Remember an "always allow for this session" choice. */
+    grant(toolName, primary) {
+        this.allow.add(primary ? `${toolName}:${primary}` : toolName);
+    }
+    /** Returns a policy fragment reflecting session grants only. */
+    toPolicy() {
+        return { allow: [...this.allow], deny: [], ask: [] };
+    }
+    clear() {
+        this.allow.clear();
+    }
+    size() {
+        return this.allow.size;
+    }
+}
+exports.SessionPermissionStore = SessionPermissionStore;
+//# sourceMappingURL=permissions.js.map

package/dist/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"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"}

package/dist/tools/extraTools.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Extra tools layered onto the core ToolRegistry for the CLI host:
+ * - todo_write: in-agent todo tracking, persisted in-memory for the session
+ * - web_fetch: GET a URL and return a trimmed text body
+ * - web_search: query a search API (Tavily), return ranked snippets
+ */
+import type { AgentTool } from '@burtson-labs/agent-core';
+interface TodoItem {
+    id: number;
+    status: 'pending' | 'in_progress' | 'done';
+    content: string;
+}
+export declare class TodoStore {
+    private items;
+    private nextId;
+    snapshot(): TodoItem[];
+    render(): string;
+    /**
+     * Accepts a JSON array of { content, status? } to replace the list, or a
+     * single string 'content' for append. Simple to be forgiving of small models.
+     */
+    upsert(raw: string): string;
+    /**
+     * A short progress summary the tool returns so the model reads a
+     * clear "update succeeded, here's what's left" signal instead of
+     * interpreting the echoed list as a reset. The trailing nudge is
+     * deliberately blunt — bandit-core-1 and similar small models have
+     * been observed to claim completion without invoking the write
+     * tool, and this helper is the most direct place to remind the
+     * model of the expectation between tool calls.
+     */
+    summary(): string;
+}
+export declare function buildTodoWriteTool(store: TodoStore): AgentTool;
+/**
+ * `remember` tool — persists a single fact to the workspace's BANDIT.md
+ * so it survives across sessions. Use case: the user says "remember
+ * that all my repos live in ~/Documents/GitHub" and wants the next
+ * Bandit session to know that without being re-told.
+ *
+ * Why a dedicated tool instead of asking the model to apply_edit
+ * BANDIT.md directly: small models (gemma4:e4b, qwen 4B) hallucinated
+ * the existing file contents when invited to edit it, and even on
+ * larger models the apply_edit dance for "append a bullet" was
+ * comically inefficient (4-5 turns minimum). This is one tool call
+ * with a single string parameter — same shape as todo_write.
+ *
+ * on the CLI: user said "you should add to your
+ * memory where my repos are", model used `todo_write` thinking it was
+ * the persistence mechanism, nothing actually landed on disk and the
+ * next session knew nothing.
+ */
+export declare function buildRememberTool(): AgentTool;
+export declare function isPrivateHost(hostname: string): Promise<boolean>;
+export declare function buildWebFetchTool(): AgentTool;
+export interface WebSearchToolOptions {
+    /** Tavily API key. Falls back to env var TAVILY_API_KEY when omitted.
+     * When neither is set, the tool returns a configuration error
+     * (model can fall back to web_fetch with a known URL). */
+    apiKey?: string;
+    /** Override the search endpoint. Default: https://api.tavily.com/search */
+    endpoint?: string;
+}
+/**
+ * Build a `web_search` tool backed by Tavily (purpose-built for LLM
+ * agents — returns ranked snippets, not raw HTML). When TAVILY_API_KEY
+ * is unset the tool returns a clear configuration error so the model
+ * can fall back to other tools (web_fetch with a known URL, ask the
+ * user, etc.) instead of hallucinating results.
+ *
+ * Why Tavily over scraping or Google CSE:
+ * - Generous free tier (1k req/mo at time of writing)
+ * - Single API call returns ranked snippets ready for the model
+ * - No CAPTCHA / rate-limit roulette like search-result scraping
+ * - Optional `answer` field gives the model an LLM-summarized answer
+ * directly when one fits the query
+ */
+export declare function buildWebSearchTool(options?: WebSearchToolOptions): AgentTool;
+export {};
+//# sourceMappingURL=extraTools.d.ts.map

package/dist/tools/extraTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraTools.d.ts","sourceRoot":"","sources":["../../src/tools/extraTools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAoC,MAAM,0BAA0B,CAAC;AAG5F,UAAU,QAAQ;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,MAAM,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAiBD,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,MAAM,CAAK;IAEnB,QAAQ,IAAI,QAAQ,EAAE;IAItB,MAAM,IAAI,MAAM;IAUhB;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IA6D3B;;;;;;;;OAQG;IACH,OAAO,IAAI,MAAM;CAiBlB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CA8C9D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,IAAI,SAAS,CAmB7C;AAuCD,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBtE;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CA4C7C;AAgBD,MAAM,WAAW,oBAAoB;IACnC;;8DAE0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAeD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,oBAAyB,GAAG,SAAS,CAsFhF"}