@alfe.ai/openclaw-knowledge 0.0.1

package/dist/plugin2.cjs

@@ -0,0 +1,358 @@
+let _alfe_ai_config = require("@alfe.ai/config");
+let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
+let node_module = require("node:module");
+//#region src/formatter.ts
+const SNIPPET_MAX = 240;
+function snippet(text) {
+	const clean = text.replace(/\s+/g, " ").trim();
+	return clean.length > SNIPPET_MAX ? `${clean.slice(0, SNIPPET_MAX)}…` : clean;
+}
+/**
+* Format RAG search hits for a tool return. Each hit carries provenance so
+* the agent can follow up: docs point at a `filePath` (already mirrored to
+* `shared/<scope>/`), facts at a `factId`.
+*/
+function formatSearchResults(result) {
+	if (result.results.length === 0) return "No matching knowledge found in your scopes.";
+	const lines = [];
+	for (const hit of result.results) {
+		const where = `${hit.scopeType}:${hit.scopeId}`;
+		const ref = hit.source === "doc" ? `doc ${hit.filePath ?? "?"}` : `fact ${hit.factId ?? "?"}`;
+		lines.push(`- [${where}] (${ref}, score ${hit.score.toFixed(2)})\n  ${snippet(hit.text)}`);
+	}
+	if (result.truncatedScopes) lines.push("(Note: you belong to more scopes than the search fan-out cap; narrow with scopeId to reach the rest.)");
+	return lines.join("\n");
+}
+/**
+* Bounded session-start context: the org profile (the headline "what is this
+* org" surface) plus a NAME-ONLY list of every scope the agent belongs to.
+* Full per-scope profiles are intentionally NOT fetched here — the agent
+* pulls those on demand via `resource_get_profile`. Mirrors the memory
+* plugin's tiered/capped auto-recall.
+*/
+function formatContextBlock(orgProfile, scopes, maxScopes) {
+	const parts = [];
+	if (orgProfile && (orgProfile.about || orgProfile.description)) {
+		parts.push("Organization profile:");
+		if (orgProfile.about) parts.push(`- About: ${snippet(orgProfile.about)}`);
+		if (orgProfile.description) parts.push(`- ${snippet(orgProfile.description)}`);
+		if (orgProfile.links.length > 0) parts.push(`- Links: ${orgProfile.links.map((l) => `${l.label} (${l.url})`).join(", ")}`);
+	}
+	if (scopes.length > 0) {
+		if (parts.length > 0) parts.push("");
+		parts.push("Your knowledge scopes (use resource_search / resource_get_profile with the scopeId):");
+		for (const s of scopes.slice(0, maxScopes)) parts.push(`- ${s.scopeType}: ${s.name} [scopeId: ${s.scopeId}]`);
+		if (scopes.length > maxScopes) parts.push(`- …and ${String(scopes.length - maxScopes)} more (call resource_list_scopes).`);
+	}
+	if (parts.length === 0) return void 0;
+	return `<knowledge-resources>\n${parts.join("\n")}\n</knowledge-resources>`;
+}
+//#endregion
+//#region src/context.ts
+/**
+* Loads bounded knowledge context at session start: the org profile plus a
+* name-only list of the agent's scopes. Called from `before_agent_start`.
+*
+* Deliberately cheap and bounded — one `listScopes` call plus (at most) one
+* org-profile fetch. Full per-scope profiles are NOT loaded; the agent pulls
+* those on demand. Membership is fixed at connect time, so this is sent once
+* per session and is stale until reconnect (mirrors SHARED_SCOPES).
+*/
+var AutoContext = class {
+	constructor(client, config, logger) {
+		this.client = client;
+		this.config = config;
+		this.logger = logger;
+	}
+	async loadForPrompt() {
+		if (!this.config.injectContext) return void 0;
+		try {
+			const { scopes } = await this.client.listScopes();
+			if (scopes.length === 0) {
+				this.logger.debug("No knowledge scopes for agent; skipping context inject");
+				return;
+			}
+			const orgScope = scopes.find((s) => s.scopeType === "org");
+			let orgProfile;
+			if (orgScope) try {
+				orgProfile = await this.client.getScopeProfile("org", orgScope.scopeId);
+			} catch (err) {
+				this.logger.debug("Org profile fetch failed; injecting scopes only", { err: String(err) });
+			}
+			const block = formatContextBlock(orgProfile, scopes, this.config.maxScopes);
+			if (block) this.logger.debug("Loaded knowledge context for prompt", {
+				scopeCount: scopes.length,
+				hasOrgProfile: orgProfile !== void 0
+			});
+			return block;
+		} catch (err) {
+			this.logger.warn("Failed to load knowledge context", { err: String(err) });
+			return;
+		}
+	}
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* knowledge — OpenClaw knowledge-resources extension.
+*
+* Scoped, searchable knowledge ABOUT a thing being worked on (org / team /
+* project). Distinct from private per-agent memory: this is SHARED,
+* attributable, deliberate-publish knowledge that humans and other agents
+* read and contribute to.
+*
+* Backed by:
+* - services/knowledge — RAG search (vector index over docs + facts)
+* - services/org       — system of record + per-agent membership gate
+*                        (docs, facts, profile)
+*
+* Registers:
+* - Tools: resource_search, resource_read_doc, resource_write_doc,
+*   resource_write_fact, resource_get_profile, resource_list_scopes
+* - Lifecycle hook: before_agent_start (bounded org-profile + scope-list inject)
+*/
+const pkg = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../package.json");
+const DEFAULT_CONFIG = {
+	injectContext: true,
+	maxScopes: 25
+};
+function resolvePluginConfig(pluginConfig) {
+	return {
+		injectContext: typeof pluginConfig?.injectContext === "boolean" ? pluginConfig.injectContext : DEFAULT_CONFIG.injectContext,
+		maxScopes: typeof pluginConfig?.maxScopes === "number" ? pluginConfig.maxScopes : DEFAULT_CONFIG.maxScopes
+	};
+}
+const SCOPE_TYPE_PROP = {
+	type: "string",
+	enum: [
+		"org",
+		"team",
+		"project"
+	],
+	description: "Scope kind. For 'org' the scopeId is the tenantId. Get exact scopeIds from resource_list_scopes."
+};
+function asScopeType(value) {
+	return value === "org" || value === "team" || value === "project" ? value : void 0;
+}
+const plugin = {
+	id: "@alfe.ai/openclaw-knowledge",
+	name: "Knowledge Resources",
+	description: "Scoped, searchable org/team/project knowledge — docs, facts, and profiles",
+	version: pkg.version,
+	register(api) {
+		const config = resolvePluginConfig(api.pluginConfig);
+		const logger = api.logger;
+		const alfeConfig = (0, _alfe_ai_config.resolveConfig)();
+		const client = new _alfe_ai_agent_api_client.AgentApiClient({
+			apiKey: alfeConfig.apiKey,
+			apiUrl: alfeConfig.apiUrl
+		});
+		const autoContext = new AutoContext(client, config, logger);
+		api.registerTool(() => ({
+			name: "resource_search",
+			label: "Resource Search",
+			description: "Semantically search shared knowledge (docs + facts) across the org, teams, and projects you belong to. Returns provenance: doc hits point at a filePath, fact hits at a factId. Docs are ALSO already synced to your workspace under shared/<scope>/, so for a small corpus just read those files directly — search earns its keep on LARGE doc corpora and on published facts. Pass scopeType+scopeId to narrow to one scope; omit to search all your scopes.",
+			parameters: {
+				type: "object",
+				properties: {
+					query: {
+						type: "string",
+						description: "What to search for"
+					},
+					limit: {
+						type: "number",
+						description: "Maximum results (default 10, max 50)"
+					},
+					scopeType: SCOPE_TYPE_PROP,
+					scopeId: {
+						type: "string",
+						description: "Narrow to one scope (from resource_list_scopes). Omit to search all."
+					}
+				},
+				required: ["query"]
+			},
+			execute: async (_toolCallId, params) => {
+				try {
+					return formatSearchResults(await client.knowledgeSearch(params.query, {
+						limit: params.limit,
+						scopeType: asScopeType(params.scopeType),
+						scopeId: typeof params.scopeId === "string" ? params.scopeId : void 0
+					}));
+				} catch (err) {
+					return `Error searching knowledge: ${err instanceof Error ? err.message : String(err)}`;
+				}
+			}
+		}), { names: ["resource_search"] });
+		api.registerTool(() => ({
+			name: "resource_read_doc",
+			label: "Resource Read Doc",
+			description: "Read the full text of a knowledge doc in a scope. Docs are also mirrored to shared/<scope>/<filePath> in your workspace — prefer reading that local file when it exists; use this when you only have a search hit's filePath.",
+			parameters: {
+				type: "object",
+				properties: {
+					scopeType: SCOPE_TYPE_PROP,
+					scopeId: {
+						type: "string",
+						description: "The scope's id (from resource_list_scopes)"
+					},
+					filePath: {
+						type: "string",
+						description: "The doc's path within the scope (e.g. notes/datacenter.md)"
+					}
+				},
+				required: [
+					"scopeType",
+					"scopeId",
+					"filePath"
+				]
+			},
+			execute: async (_toolCallId, params) => {
+				const scopeType = asScopeType(params.scopeType);
+				if (!scopeType) return "Error: scopeType must be one of org, team, project.";
+				try {
+					const { text } = await client.readScopeDoc(scopeType, params.scopeId, params.filePath);
+					return text;
+				} catch (err) {
+					return `Error reading doc: ${err instanceof Error ? err.message : String(err)}`;
+				}
+			}
+		}), { names: ["resource_read_doc"] });
+		api.registerTool(() => ({
+			name: "resource_write_doc",
+			label: "Resource Write Doc",
+			description: "Create or overwrite a knowledge DOC in a scope. Use a DOC for durable, reshaped, human-readable prose that grows and is curated over time — runbooks, designs, onboarding notes, an evolving description of a system. Use resource_write_fact instead for a single crisp atomic statement. Writing is a DELIBERATE publish into shared, attributable knowledge (not your private memory). Overwriting an existing path creates a new revision (history is kept).",
+			parameters: {
+				type: "object",
+				properties: {
+					scopeType: SCOPE_TYPE_PROP,
+					scopeId: {
+						type: "string",
+						description: "The scope's id (from resource_list_scopes)"
+					},
+					filePath: {
+						type: "string",
+						description: "Path within the scope, e.g. designs/data-center.md"
+					},
+					content: {
+						type: "string",
+						description: "Full markdown content of the doc"
+					},
+					message: {
+						type: "string",
+						description: "Optional revision note describing the change"
+					}
+				},
+				required: [
+					"scopeType",
+					"scopeId",
+					"filePath",
+					"content"
+				]
+			},
+			execute: async (_toolCallId, params) => {
+				const scopeType = asScopeType(params.scopeType);
+				if (!scopeType) return "Error: scopeType must be one of org, team, project.";
+				try {
+					const { filePath } = await client.writeScopeDoc(scopeType, params.scopeId, params.filePath, params.content, { message: typeof params.message === "string" ? params.message : void 0 });
+					return `Wrote doc ${filePath} to ${scopeType}:${String(params.scopeId)}.`;
+				} catch (err) {
+					return `Error writing doc: ${err instanceof Error ? err.message : String(err)}`;
+				}
+			}
+		}), { names: ["resource_write_doc"] });
+		api.registerTool(() => ({
+			name: "resource_write_fact",
+			label: "Resource Write Fact",
+			description: "Publish a single crisp FACT into a scope's shared knowledge. Use a FACT for one atomic, durable statement worth remembering across agents (e.g. 'The prod data center is in Hetzner FSN1', 'The billing owner is Kevin'). Use resource_write_doc instead for longer curated prose. This is a DELIBERATE, attributable cross-agent publish — it is NOT your private memory and is NOT an automatic merge. Keep it short and self-contained.",
+			parameters: {
+				type: "object",
+				properties: {
+					scopeType: SCOPE_TYPE_PROP,
+					scopeId: {
+						type: "string",
+						description: "The scope's id (from resource_list_scopes)"
+					},
+					text: {
+						type: "string",
+						description: "The fact — one atomic, self-contained statement"
+					}
+				},
+				required: [
+					"scopeType",
+					"scopeId",
+					"text"
+				]
+			},
+			execute: async (_toolCallId, params) => {
+				const scopeType = asScopeType(params.scopeType);
+				if (!scopeType) return "Error: scopeType must be one of org, team, project.";
+				try {
+					return `Published fact ${(await client.createScopeFact(scopeType, params.scopeId, params.text)).factId} to ${scopeType}:${String(params.scopeId)}.`;
+				} catch (err) {
+					return `Error publishing fact: ${err instanceof Error ? err.message : String(err)}`;
+				}
+			}
+		}), { names: ["resource_write_fact"] });
+		api.registerTool(() => ({
+			name: "resource_get_profile",
+			label: "Resource Get Profile",
+			description: "Fetch the structured profile (about / description / links) for one scope. Use this to learn what a specific team or project is, on demand — the session-start context only lists scope names, not their full profiles.",
+			parameters: {
+				type: "object",
+				properties: {
+					scopeType: SCOPE_TYPE_PROP,
+					scopeId: {
+						type: "string",
+						description: "The scope's id (from resource_list_scopes)"
+					}
+				},
+				required: ["scopeType", "scopeId"]
+			},
+			execute: async (_toolCallId, params) => {
+				const scopeType = asScopeType(params.scopeType);
+				if (!scopeType) return "Error: scopeType must be one of org, team, project.";
+				try {
+					const p = await client.getScopeProfile(scopeType, params.scopeId);
+					const lines = [`Profile for ${scopeType}:${String(params.scopeId)}`];
+					if (p.about) lines.push(`About: ${p.about}`);
+					if (p.description) lines.push(p.description);
+					if (p.links.length > 0) lines.push(`Links: ${p.links.map((l) => `${l.label} (${l.url})`).join(", ")}`);
+					if (lines.length === 1) lines.push("(no profile set)");
+					return lines.join("\n");
+				} catch (err) {
+					return `Error fetching profile: ${err instanceof Error ? err.message : String(err)}`;
+				}
+			}
+		}), { names: ["resource_get_profile"] });
+		api.registerTool(() => ({
+			name: "resource_list_scopes",
+			label: "Resource List Scopes",
+			description: "List every knowledge scope you belong to (org + teams + projects) with each scope's exact scopeId. Call this to discover the scopeId to pass to the other resource_* tools (for 'org', scopeId is the tenantId).",
+			parameters: {
+				type: "object",
+				properties: {}
+			},
+			execute: async () => {
+				try {
+					const { scopes } = await client.listScopes();
+					if (scopes.length === 0) return "You do not belong to any knowledge scopes.";
+					return scopes.map((s) => `- ${s.scopeType}: ${s.name} [scopeId: ${s.scopeId}]`).join("\n");
+				} catch (err) {
+					return `Error listing scopes: ${err instanceof Error ? err.message : String(err)}`;
+				}
+			}
+		}), { names: ["resource_list_scopes"] });
+		api.on("before_agent_start", async () => {
+			const block = await autoContext.loadForPrompt();
+			if (block) return { prependContext: block };
+		}, { priority: 10 });
+		logger.info("knowledge extension registered", { injectContext: config.injectContext });
+	}
+};
+//#endregion
+Object.defineProperty(exports, "plugin", {
+	enumerable: true,
+	get: function() {
+		return plugin;
+	}
+});