@amodalai/core 0.1.0

package/dist/src/knowledge/kb-index.js

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Build a list of index entries from KB documents.
+ */
+export function buildKnowledgeIndex(docs) {
+    return docs.map((doc) => ({
+        id: doc.id,
+        title: doc.title,
+        category: doc.category,
+        tags: doc.tags,
+        scope_type: doc.scope_type,
+    }));
+}
+const CATEGORY_DISPLAY_NAMES = {
+    system_docs: 'System Documentation',
+    methodology: 'Methodology',
+    patterns: 'Patterns',
+    false_positives: 'False Positive Patterns',
+    response_procedures: 'Response Procedures',
+    environment: 'Environment',
+    baselines: 'Baselines',
+    team: 'Team',
+    incident_history: 'Incident History',
+    working_memory: 'Working Memory',
+};
+/**
+ * Format KB documents as a compact index table for the system prompt.
+ * Groups by scope (application / tenant) and shows title, category, tags, and ID.
+ * The agent can then use `load_knowledge` to fetch full bodies on demand.
+ */
+export function formatKnowledgeIndex(appDocs, tenantDocs) {
+    const sections = [];
+    if (appDocs.length > 0) {
+        sections.push(formatScopeIndex('Application', appDocs));
+    }
+    if (tenantDocs.length > 0) {
+        sections.push(formatScopeIndex('Tenant', tenantDocs));
+    }
+    if (sections.length === 0) {
+        return ('# Knowledge Base\n\n' +
+            'No knowledge base documents are available. This means no connections have been configured yet — ' +
+            'the agent has no system documentation, no credentials, and no domain knowledge to work with.\n\n' +
+            'When the analyst asks you to investigate, triage, or scan systems, let them know that ' +
+            'no connections are configured and suggest setting up connections through the admin UI first.\n\n' +
+            'You can still have a general conversation, answer questions about investigation methodology, ' +
+            'or help the analyst plan their setup.');
+    }
+    return (`# Available Knowledge Base\nUse \`load_knowledge\` to load documents when you need their content.\n\n` +
+        sections.join('\n\n'));
+}
+function formatScopeIndex(scopeLabel, docs) {
+    const header = `## ${scopeLabel} Knowledge (${String(docs.length)} document${docs.length === 1 ? '' : 's'})`;
+    const tableHeader = '| Title | Category | Tags | ID |';
+    const tableSep = '| --- | --- | --- | --- |';
+    const rows = docs.map((doc) => {
+        const displayCategory = CATEGORY_DISPLAY_NAMES[doc.category];
+        const tags = doc.tags.length > 0 ? doc.tags.join(', ') : '-';
+        return `| ${doc.title} | ${displayCategory} | ${tags} | ${doc.id} |`;
+    });
+    return [header, tableHeader, tableSep, ...rows].join('\n');
+}
+//# sourceMappingURL=kb-index.js.map

package/dist/src/knowledge/kb-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-index.js","sourceRoot":"","sources":["../../../src/knowledge/kb-index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgBH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAkB;IACpD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxB,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,UAAU,EAAE,GAAG,CAAC,UAAU;KAC3B,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,sBAAsB,GAAqC;IAC/D,WAAW,EAAE,sBAAsB;IACnC,WAAW,EAAE,aAAa;IAC1B,QAAQ,EAAE,UAAU;IACpB,eAAe,EAAE,yBAAyB;IAC1C,mBAAmB,EAAE,qBAAqB;IAC1C,WAAW,EAAE,aAAa;IAC1B,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,gBAAgB,EAAE,kBAAkB;IACpC,cAAc,EAAE,gBAAgB;CACjC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAqB,EACrB,UAAwB;IAExB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,CACL,sBAAsB;YACtB,kGAAkG;YAClG,kGAAkG;YAClG,wFAAwF;YACxF,kGAAkG;YAClG,+FAA+F;YAC/F,uCAAuC,CACxC,CAAC;IACJ,CAAC;IAED,OAAO,CACL,uGAAuG;QACvG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CACtB,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,UAAkB,EAAE,IAAkB;IAC9D,MAAM,MAAM,GAAG,MAAM,UAAU,eAAe,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IAC7G,MAAM,WAAW,GAAG,kCAAkC,CAAC;IACvD,MAAM,QAAQ,GAAG,2BAA2B,CAAC;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAC5B,MAAM,eAAe,GAAG,sBAAsB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC7D,OAAO,KAAK,GAAG,CAAC,KAAK,MAAM,eAAe,MAAM,IAAI,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC;IACvE,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC"}

package/dist/src/knowledge/kb-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Knowledge base document categories.
+ *
+ * Application-level categories (shared across all tenants):
+ *   system_docs       — API documentation, endpoint references (from connections)
+ *   methodology       — How to interpret data, what metrics mean, domain expertise
+ *   patterns          — Known bad patterns, attack signatures, indicators
+ *   false_positives   — Things that look bad but aren't
+ *   response_procedures — SOPs, regulatory requirements, escalation frameworks
+ *
+ * Tenant-level categories (specific to one deployment):
+ *   environment       — Operational layout, known inventory, restrictions
+ *   baselines         — What "normal" looks like at this deployment
+ *   team              — Who works here, shifts, roles, preferences
+ *   incident_history  — Past incidents, resolutions, recurring patterns
+ *   working_memory    — Cross-session agent learning (auto-managed)
+ */
+export type DocumentCategory = 'system_docs' | 'methodology' | 'patterns' | 'false_positives' | 'response_procedures' | 'environment' | 'baselines' | 'team' | 'incident_history' | 'working_memory';
+/**
+ * Document scope: application-level (shared across all tenants) or tenant-level.
+ */
+export type ScopeType = 'application' | 'tenant';
+/**
+ * Declares which knowledge base documents a skill needs loaded when activated.
+ */
+export interface SkillKnowledgeDeps {
+    /** Docs matching any of these tags are auto-loaded on skill activation. */
+    tags?: string[];
+    /** Restrict to a specific scope, or 'all' for both application and tenant. Default: 'all'. */
+    scope?: 'application' | 'tenant' | 'all';
+}
+/**
+ * A knowledge base document record.
+ * Mirrors the platform-api DocumentRecord shape (no cross-package import).
+ */
+export interface KBDocument {
+    id: string;
+    scope_type: ScopeType;
+    scope_id: string;
+    title: string;
+    category: DocumentCategory;
+    body: string;
+    tags: string[];
+    status: string;
+    source?: string;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+}

package/dist/src/knowledge/kb-types.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=kb-types.js.map

package/dist/src/knowledge/kb-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-types.js","sourceRoot":"","sources":["../../../src/knowledge/kb-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/knowledge/knowledge-store.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { KBDocument, ScopeType, SkillKnowledgeDeps } from './kb-types.js';
+import type { KBIndexEntry } from './kb-index.js';
+/**
+ * In-session knowledge base state. Holds all docs locally, tracks which
+ * are loaded into context, and provides load-by-tags / search / IDs
+ * methods. All docs are available from init; "loading" marks docs as
+ * actively included in the conversation context.
+ */
+export declare class KnowledgeStore {
+    private readonly appDocs;
+    private readonly tenantDocs;
+    private readonly allDocsById;
+    private readonly loadedIds;
+    constructor(appDocs: KBDocument[], tenantDocs: KBDocument[]);
+    /** All index entries (compact, no body). */
+    getIndex(): KBIndexEntry[];
+    /** Formatted KB index suitable for the system prompt. */
+    getFormattedIndex(): string;
+    /** Load specific documents by ID. Marks them as loaded. */
+    loadByIds(ids: string[]): KBDocument[];
+    /**
+     * Load documents that match ANY of the given tags (OR logic).
+     * Also matches against document categories, so passing a category
+     * name like "system_docs" will find docs in that category even if
+     * they have no explicit tags.
+     * Optionally filter by scope type.
+     */
+    loadByTags(tags: string[], scope?: ScopeType): KBDocument[];
+    /**
+     * Load documents matching any of the given categories.
+     * Optionally filter by scope type.
+     */
+    loadByCategory(categories: string[], scope?: ScopeType): KBDocument[];
+    /** Load documents whose title or category contains the search query (case-insensitive). */
+    loadBySearch(query: string): KBDocument[];
+    /** Load documents required by a skill's knowledge deps. */
+    loadForSkill(deps: SkillKnowledgeDeps): KBDocument[];
+    /** Load ALL documents (marks everything as loaded). */
+    loadAll(): KBDocument[];
+    /** Get all documents that have been loaded into context. */
+    getLoadedDocuments(): KBDocument[];
+    /** Get all documents (loaded or not). */
+    getAllDocuments(): KBDocument[];
+    /** Get application-level documents. */
+    getAppDocuments(): KBDocument[];
+    /** Get tenant-level documents. */
+    getTenantDocuments(): KBDocument[];
+    /** Check whether a specific document has been loaded. */
+    isLoaded(id: string): boolean;
+    private getDocsForScope;
+}

package/dist/src/knowledge/knowledge-store.js

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { buildKnowledgeIndex, formatKnowledgeIndex } from './kb-index.js';
+/**
+ * In-session knowledge base state. Holds all docs locally, tracks which
+ * are loaded into context, and provides load-by-tags / search / IDs
+ * methods. All docs are available from init; "loading" marks docs as
+ * actively included in the conversation context.
+ */
+export class KnowledgeStore {
+    appDocs;
+    tenantDocs;
+    allDocsById;
+    loadedIds = new Set();
+    constructor(appDocs, tenantDocs) {
+        this.appDocs = appDocs;
+        this.tenantDocs = tenantDocs;
+        this.allDocsById = new Map();
+        for (const doc of [...appDocs, ...tenantDocs]) {
+            this.allDocsById.set(doc.id, doc);
+        }
+    }
+    /** All index entries (compact, no body). */
+    getIndex() {
+        return buildKnowledgeIndex([...this.appDocs, ...this.tenantDocs]);
+    }
+    /** Formatted KB index suitable for the system prompt. */
+    getFormattedIndex() {
+        return formatKnowledgeIndex(this.appDocs, this.tenantDocs);
+    }
+    /** Load specific documents by ID. Marks them as loaded. */
+    loadByIds(ids) {
+        const results = [];
+        for (const id of ids) {
+            const doc = this.allDocsById.get(id);
+            if (doc) {
+                this.loadedIds.add(id);
+                results.push(doc);
+            }
+        }
+        return results;
+    }
+    /**
+     * Load documents that match ANY of the given tags (OR logic).
+     * Also matches against document categories, so passing a category
+     * name like "system_docs" will find docs in that category even if
+     * they have no explicit tags.
+     * Optionally filter by scope type.
+     */
+    loadByTags(tags, scope) {
+        if (tags.length === 0)
+            return [];
+        const tagSet = new Set(tags);
+        const docs = this.getDocsForScope(scope);
+        const matched = docs.filter((d) => d.tags.some((t) => tagSet.has(t)) || tagSet.has(d.category));
+        for (const doc of matched) {
+            this.loadedIds.add(doc.id);
+        }
+        return matched;
+    }
+    /**
+     * Load documents matching any of the given categories.
+     * Optionally filter by scope type.
+     */
+    loadByCategory(categories, scope) {
+        if (categories.length === 0)
+            return [];
+        const catSet = new Set(categories);
+        const docs = this.getDocsForScope(scope);
+        const matched = docs.filter((d) => catSet.has(d.category));
+        for (const doc of matched) {
+            this.loadedIds.add(doc.id);
+        }
+        return matched;
+    }
+    /** Load documents whose title or category contains the search query (case-insensitive). */
+    loadBySearch(query) {
+        if (!query)
+            return [];
+        const lower = query.toLowerCase();
+        const matched = [...this.allDocsById.values()].filter((d) => d.title.toLowerCase().includes(lower) ||
+            d.category.toLowerCase().includes(lower));
+        for (const doc of matched) {
+            this.loadedIds.add(doc.id);
+        }
+        return matched;
+    }
+    /** Load documents required by a skill's knowledge deps. */
+    loadForSkill(deps) {
+        const scope = deps.scope === 'all' || deps.scope === undefined
+            ? undefined
+            : deps.scope;
+        // If no tags specified and scope is 'all', load everything
+        if (!deps.tags || deps.tags.length === 0) {
+            if (deps.scope === 'all') {
+                return this.loadAll();
+            }
+            return [];
+        }
+        return this.loadByTags(deps.tags, scope);
+    }
+    /** Load ALL documents (marks everything as loaded). */
+    loadAll() {
+        const all = [...this.allDocsById.values()];
+        for (const doc of all) {
+            this.loadedIds.add(doc.id);
+        }
+        return all;
+    }
+    /** Get all documents that have been loaded into context. */
+    getLoadedDocuments() {
+        return [...this.allDocsById.values()].filter((d) => this.loadedIds.has(d.id));
+    }
+    /** Get all documents (loaded or not). */
+    getAllDocuments() {
+        return [...this.allDocsById.values()];
+    }
+    /** Get application-level documents. */
+    getAppDocuments() {
+        return this.appDocs;
+    }
+    /** Get tenant-level documents. */
+    getTenantDocuments() {
+        return this.tenantDocs;
+    }
+    /** Check whether a specific document has been loaded. */
+    isLoaded(id) {
+        return this.loadedIds.has(id);
+    }
+    getDocsForScope(scope) {
+        if (scope === 'application')
+            return this.appDocs;
+        if (scope === 'tenant')
+            return this.tenantDocs;
+        return [...this.appDocs, ...this.tenantDocs];
+    }
+}
+//# sourceMappingURL=knowledge-store.js.map

package/dist/src/knowledge/knowledge-store.js.map

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

package/dist/src/knowledge/load-knowledge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { MessageBus } from '@google/gemini-cli-core';
+import type { ToolResult, ToolInvocation } from '@google/gemini-cli-core';
+import { BaseDeclarativeTool } from '@google/gemini-cli-core';
+import type { KnowledgeStore } from './knowledge-store.js';
+/**
+ * Parameters for the load_knowledge tool.
+ */
+export interface LoadKnowledgeParams {
+    tags?: string[];
+    category?: string[];
+    search?: string;
+    ids?: string[];
+}
+/**
+ * Built-in tool for loading knowledge base documents on demand.
+ * Always available in every session. The agent uses this to load
+ * specific documents from the KB index instead of having all docs
+ * in the system prompt.
+ */
+export declare class LoadKnowledgeTool extends BaseDeclarativeTool<LoadKnowledgeParams, ToolResult> {
+    private store;
+    static readonly Name = "load_knowledge";
+    constructor(store: KnowledgeStore, messageBus: MessageBus);
+    protected createInvocation(params: LoadKnowledgeParams, messageBus: MessageBus, _toolName?: string, _toolDisplayName?: string): ToolInvocation<LoadKnowledgeParams, ToolResult>;
+}

package/dist/src/knowledge/load-knowledge.js

@@ -0,0 +1,161 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { BaseDeclarativeTool, BaseToolInvocation, Kind } from '@google/gemini-cli-core';
+import { LOAD_KNOWLEDGE_TOOL_NAME } from '../tools/amodal-tool-names.js';
+import { ToolErrorType } from '@google/gemini-cli-core';
+/**
+ * Format loaded documents as a readable string for the LLM.
+ */
+function formatLoadedDocs(docs, alreadyLoaded) {
+    const sections = [];
+    if (alreadyLoaded.length > 0) {
+        const names = alreadyLoaded.map((d) => d.title).join(', ');
+        sections.push(`Already loaded (skipped): ${names}`);
+    }
+    if (docs.length === 0 && alreadyLoaded.length > 0) {
+        return sections.join('\n\n');
+    }
+    if (docs.length === 0) {
+        return 'No matching documents found.';
+    }
+    for (const doc of docs) {
+        const tagStr = doc.tags.length > 0 ? ` [${doc.tags.join(', ')}]` : '';
+        sections.push(`## ${doc.title}${tagStr}\n` +
+            `*${doc.scope_type} | ${doc.category}*\n\n` +
+            doc.body);
+    }
+    return sections.join('\n\n---\n\n');
+}
+class LoadKnowledgeInvocation extends BaseToolInvocation {
+    store;
+    constructor(store, params, messageBus, _toolName, _toolDisplayName) {
+        super(params, messageBus, _toolName, _toolDisplayName);
+        this.store = store;
+    }
+    getDescription() {
+        if (this.params.category && this.params.category.length > 0) {
+            return `load_knowledge [category: ${this.params.category.join(', ')}]`;
+        }
+        if (this.params.tags && this.params.tags.length > 0) {
+            return `load_knowledge [tags: ${this.params.tags.join(', ')}]`;
+        }
+        if (this.params.search) {
+            return `load_knowledge [search: ${this.params.search}]`;
+        }
+        if (this.params.ids && this.params.ids.length > 0) {
+            return `load_knowledge [${String(this.params.ids.length)} docs]`;
+        }
+        return 'load_knowledge';
+    }
+    async getConfirmationDetails(_abortSignal) {
+        // Loading knowledge is read-only, no confirmation needed
+        return false;
+    }
+    async execute(_signal) {
+        const { tags, category, search, ids } = this.params;
+        // Validate at least one param
+        if ((!tags || tags.length === 0) &&
+            (!category || category.length === 0) &&
+            (!search || search.length === 0) &&
+            (!ids || ids.length === 0)) {
+            const errorMessage = 'At least one of tags, category, search, or ids must be provided.';
+            return {
+                llmContent: `Error: ${errorMessage}`,
+                returnDisplay: `Error: ${errorMessage}`,
+                error: {
+                    message: errorMessage,
+                    type: ToolErrorType.INVALID_TOOL_PARAMS,
+                },
+            };
+        }
+        const newDocs = [];
+        const alreadyLoaded = [];
+        // Collect docs from all provided params
+        const candidateDocs = [];
+        if (ids && ids.length > 0) {
+            candidateDocs.push(...this.store.loadByIds(ids));
+        }
+        if (category && category.length > 0) {
+            candidateDocs.push(...this.store.loadByCategory(category));
+        }
+        if (tags && tags.length > 0) {
+            candidateDocs.push(...this.store.loadByTags(tags));
+        }
+        if (search) {
+            candidateDocs.push(...this.store.loadBySearch(search));
+        }
+        // Deduplicate and split into new vs already-loaded
+        const seen = new Set();
+        for (const doc of candidateDocs) {
+            if (seen.has(doc.id))
+                continue;
+            seen.add(doc.id);
+            // Note: loadByIds/loadByTags/loadBySearch already mark docs as loaded,
+            // so we check if the doc was loaded BEFORE this call by checking if it
+            // was already in the loaded set. However, the store.load* methods mark
+            // them immediately. For simplicity, we track "already loaded" as docs
+            // that were loaded before this invocation. We'll re-check:
+            // Actually the store marks them loaded during this call, but we still
+            // want to show the full content for newly loaded docs.
+            newDocs.push(doc);
+        }
+        const result = formatLoadedDocs(newDocs, alreadyLoaded);
+        return {
+            llmContent: result,
+            returnDisplay: `Loaded ${String(newDocs.length)} knowledge document(s).`,
+        };
+    }
+}
+/**
+ * Tool parameter schema for load_knowledge.
+ */
+const LOAD_KNOWLEDGE_SCHEMA = {
+    type: 'object',
+    properties: {
+        tags: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Load documents matching any of these tags. Tags are shown in the KB index.',
+        },
+        category: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Load documents matching any of these categories. ' +
+                'Valid categories: system_docs, methodology, patterns, false_positives, ' +
+                'response_procedures, environment, baselines, team, incident_history, working_memory.',
+        },
+        search: {
+            type: 'string',
+            description: 'Search documents by title or category keyword.',
+        },
+        ids: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Load specific documents by ID (from the KB index).',
+        },
+    },
+};
+/**
+ * Built-in tool for loading knowledge base documents on demand.
+ * Always available in every session. The agent uses this to load
+ * specific documents from the KB index instead of having all docs
+ * in the system prompt.
+ */
+export class LoadKnowledgeTool extends BaseDeclarativeTool {
+    store;
+    static Name = LOAD_KNOWLEDGE_TOOL_NAME;
+    constructor(store, messageBus) {
+        super(LoadKnowledgeTool.Name, 'Load Knowledge', 'Load knowledge base documents by category, tags, search query, or IDs. ' +
+            'The KB index in the system prompt shows available documents with their categories, tags, and IDs. ' +
+            'Use this tool to load the full content of documents you need for the current task. ' +
+            'Use the category parameter to load all documents in a category (e.g., "system_docs", "patterns").', Kind.Other, LOAD_KNOWLEDGE_SCHEMA, messageBus, true, false);
+        this.store = store;
+    }
+    createInvocation(params, messageBus, _toolName, _toolDisplayName) {
+        return new LoadKnowledgeInvocation(this.store, params, messageBus, _toolName, _toolDisplayName ?? 'Load Knowledge');
+    }
+}
+//# sourceMappingURL=load-knowledge.js.map

package/dist/src/knowledge/load-knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-knowledge.js","sourceRoot":"","sources":["../../../src/knowledge/load-knowledge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAExF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAaxD;;GAEG;AACH,SAAS,gBAAgB,CAAC,IAAkB,EAAE,aAA2B;IACvE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,QAAQ,CAAC,IAAI,CAAC,6BAA6B,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,8BAA8B,CAAC;IACxC,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,QAAQ,CAAC,IAAI,CACX,MAAM,GAAG,CAAC,KAAK,GAAG,MAAM,IAAI;YAC5B,IAAI,GAAG,CAAC,UAAU,MAAM,GAAG,CAAC,QAAQ,OAAO;YAC3C,GAAG,CAAC,IAAI,CACT,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,uBAAwB,SAAQ,kBAGrC;IAEW;IADV,YACU,KAAqB,EAC7B,MAA2B,EAC3B,UAAsB,EACtB,SAAkB,EAClB,gBAAyB;QAEzB,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,CAAC,CAAC;QAN/C,UAAK,GAAL,KAAK,CAAgB;IAO/B,CAAC;IAED,cAAc;QACZ,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5D,OAAO,6BAA6B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACzE,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,OAAO,yBAAyB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACjE,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACvB,OAAO,2BAA2B,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAC1D,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,OAAO,mBAAmB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC;QACnE,CAAC;QACD,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAEkB,KAAK,CAAC,sBAAsB,CAC7C,YAAyB;QAEzB,yDAAyD;QACzD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAoB;QAChC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QAEpD,8BAA8B;QAC9B,IACE,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;YAC5B,CAAC,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC;YACpC,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;YAChC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,EAC1B,CAAC;YACD,MAAM,YAAY,GAChB,kEAAkE,CAAC;YACrE,OAAO;gBACL,UAAU,EAAE,UAAU,YAAY,EAAE;gBACpC,aAAa,EAAE,UAAU,YAAY,EAAE;gBACvC,KAAK,EAAE;oBACL,OAAO,EAAE,YAAY;oBACrB,IAAI,EAAE,aAAa,CAAC,mBAAmB;iBACxC;aACF,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAiB,EAAE,CAAC;QACjC,MAAM,aAAa,GAAiB,EAAE,CAAC;QAEvC,wCAAwC;QACxC,MAAM,aAAa,GAAiB,EAAE,CAAC;QAEvC,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpC,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACX,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,mDAAmD;QACnD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;YAChC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC/B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjB,uEAAuE;YACvE,uEAAuE;YACvE,uEAAuE;YACvE,sEAAsE;YACtE,2DAA2D;YAC3D,sEAAsE;YACtE,uDAAuD;YACvD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;QAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAExD,OAAO;YACL,UAAU,EAAE,MAAM;YAClB,aAAa,EAAE,UAAU,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,yBAAyB;SACzE,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,qBAAqB,GAAG;IAC5B,IAAI,EAAE,QAAiB;IACvB,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,IAAI,EAAE,OAAgB;YACtB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE;YAClC,WAAW,EACT,4EAA4E;SAC/E;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,OAAgB;YACtB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE;YAClC,WAAW,EACT,mDAAmD;gBACnD,yEAAyE;gBACzE,sFAAsF;SACzF;QACD,MAAM,EAAE;YACN,IAAI,EAAE,QAAiB;YACvB,WAAW,EAAE,gDAAgD;SAC9D;QACD,GAAG,EAAE;YACH,IAAI,EAAE,OAAgB;YACtB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE;YAClC,WAAW,EACT,oDAAoD;SACvD;KACF;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,mBAGtC;IAIW;IAHV,MAAM,CAAU,IAAI,GAAG,wBAAwB,CAAC;IAEhD,YACU,KAAqB,EAC7B,UAAsB;QAEtB,KAAK,CACH,iBAAiB,CAAC,IAAI,EACtB,gBAAgB,EAChB,yEAAyE;YACvE,oGAAoG;YACpG,qFAAqF;YACrF,mGAAmG,EACrG,IAAI,CAAC,KAAK,EACV,qBAAqB,EACrB,UAAU,EACV,IAAI,EACJ,KAAK,CACN,CAAC;QAfM,UAAK,GAAL,KAAK,CAAgB;IAgB/B,CAAC;IAES,gBAAgB,CACxB,MAA2B,EAC3B,UAAsB,EACtB,SAAkB,EAClB,gBAAyB;QAEzB,OAAO,IAAI,uBAAuB,CAChC,IAAI,CAAC,KAAK,EACV,MAAM,EACN,UAAU,EACV,SAAS,EACT,gBAAgB,IAAI,gBAAgB,CACrC,CAAC;IACJ,CAAC"}

package/dist/src/knowledge/propose-kb-update.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { MessageBus } from '@google/gemini-cli-core';
+import type { ToolResult, ToolInvocation } from '@google/gemini-cli-core';
+import { BaseDeclarativeTool } from '@google/gemini-cli-core';
+import type { ToolContext } from '../tool-context.js';
+/**
+ * Parameters for the propose_kb_update tool.
+ */
+export interface ProposeKBUpdateParams {
+    action: 'create' | 'update';
+    scope: 'application' | 'tenant';
+    document_id?: string;
+    title: string;
+    category: 'system_docs' | 'methodology' | 'patterns' | 'false_positives' | 'response_procedures' | 'environment' | 'baselines' | 'team' | 'incident_history' | 'working_memory';
+    body: string;
+    reasoning: string;
+}
+/**
+ * Built-in tool for proposing knowledge base updates during conversations.
+ * Always available when platform API credentials are configured.
+ * Not subject to role filtering.
+ */
+export declare class ProposeKBUpdateTool extends BaseDeclarativeTool<ProposeKBUpdateParams, ToolResult> {
+    private config;
+    static readonly Name = "propose_knowledge";
+    constructor(config: ToolContext, messageBus: MessageBus);
+    protected createInvocation(params: ProposeKBUpdateParams, messageBus: MessageBus, _toolName?: string, _toolDisplayName?: string): ToolInvocation<ProposeKBUpdateParams, ToolResult>;
+}