@alfe.ai/openclaw-knowledge 0.0.18 → 0.0.20

package/README.md

@@ -0,0 +1,47 @@
+# `@alfe.ai/openclaw-knowledge`
+
+OpenClaw tools for shared, scoped knowledge about an organization, team, or
+project. Shared knowledge consists of curated documents and a structured scope
+profile. Quick or uncertain capture belongs in private per-agent memory; there
+is no shared free-floating facts primitive.
+
+The plugin exposes seven tools:
+
+- `resource_search` searches the RAG projection and returns document paths.
+- `resource_read_doc` reads a bounded document by explicit scope and path.
+- `resource_write_doc` writes a document while retaining revision history.
+- `resource_get_profile` reads one scope profile.
+- `resource_list_scopes` discovers exact member scope IDs.
+- `resource_propose_change` opens an inert review request for a non-member scope.
+- `resource_list_change_requests` pages through the agent's own proposals.
+
+## Boundary and authorization model
+
+Every resource operation takes an explicit `scopeType` and `scopeId`. The org
+service remains the system of record and enforces membership for reads/direct
+writes; the knowledge service is only the searchable projection. A proposal
+does not grant read access and changes nothing until an authorized reviewer
+approves it.
+
+Runtime validation mirrors the service limits for queries, identifiers, paths,
+documents, profiles, and proposal pages. Direct document downloads stop at the
+2 MiB index boundary, while the model-facing read tool uses a 256 KiB cap and
+directs larger reads to the synced `shared/` workspace. Session-start context
+is escaped, line-bounded, and capped at 16 KiB because profile and scope names
+are shared data, not trusted prompt instructions.
+
+## Development
+
+```bash
+pnpm --filter @alfe.ai/openclaw-knowledge lint
+pnpm --filter @alfe.ai/openclaw-knowledge typecheck
+pnpm --filter @alfe.ai/openclaw-knowledge test
+pnpm --filter @alfe.ai/openclaw-knowledge build
+```
+
+The package publishes ESM and CJS entrypoints. Its default-only plugin entry
+and complete static tool catalog must stay aligned with
+`openclaw.plugin.json`.
+
+Part of [Alfe](https://alfe.ai). See the [documentation](https://docs.alfe.ai)
+for platform setup.

package/dist/index.d.cts

@@ -1,101 +1,2 @@
-import plugin from "./plugin.cjs";
-
-//#region ../agent-api-client/dist/index.d.ts
-
-type KnowledgeScopeType = "org" | "team" | "project";
-interface KnowledgeScope {
-  scopeType: KnowledgeScopeType;
-  scopeId: string;
-  name: string;
-}
-interface KnowledgeSearchHit {
-  id: string;
-  text: string;
-  /** Normalized relevance in (0,1]; higher = closer. */
-  score: number;
-  scopeType: KnowledgeScopeType;
-  scopeId: string;
-  /**
-   * Provenance of the hit. All live results are `"doc"`; `"fact"` only ever
-   * appears for legacy vectors indexed before the facts primitive was removed
-   * (the search index stays tolerant of them). Treat every hit as a doc.
-   */
-  source: "doc" | "fact";
-  /** The canonical file under shared/<scope>/ (present on doc hits). */
-  filePath?: string;
-  /** Legacy-only: the id of a pre-removal fact vector. */
-  factId?: string;
-}
-interface KnowledgeSearchResult {
-  results: KnowledgeSearchHit[];
-  /** True when fan-out breadth was capped (more member scopes than the cap). */
-  truncatedScopes: boolean;
-}
-interface KnowledgeProfileLink {
-  label: string;
-  url: string;
-}
-interface KnowledgeProfile {
-  scopeType: KnowledgeScopeType;
-  scopeId: string;
-  about: string | null;
-  description: string | null;
-  links: KnowledgeProfileLink[];
-  updatedAt: string | null;
-  updatedBy: string | null;
-}
-interface KnowledgeDoc {
-  filePath: string;
-  fileName: string;
-  contentType?: string;
-  size: number;
-  uploadedBy?: string;
-  createdAt: string;
-  updatedAt: string;
-}
-//#endregion
-//#region src/types.d.ts
-interface KnowledgeConfig {
-  /** Inject org profile + name-only scope list at session start. */
-  injectContext: boolean;
-  /** Cap on scopes listed in the session-start context block. */
-  maxScopes: number;
-}
-/**
- * The subset of `AgentApiClient` the plugin needs. Declaring it as an
- * interface (rather than importing the concrete class everywhere) keeps the
- * injection/formatting code decoupled and unit-testable — the real
- * `AgentApiClient` structurally satisfies it.
- */
-interface KnowledgeApi {
-  knowledgeSearch(query: string, opts?: {
-    limit?: number;
-    scopeType?: KnowledgeScopeType;
-    scopeId?: string;
-  }): Promise<KnowledgeSearchResult>;
-  listScopes(): Promise<{
-    scopes: KnowledgeScope[];
-  }>;
-  getScopeProfile(scopeType: KnowledgeScopeType, scopeId: string): Promise<KnowledgeProfile>;
-  listScopeDocs(scopeType: KnowledgeScopeType, scopeId: string, opts?: {
-    limit?: number;
-    cursor?: string;
-  }): Promise<{
-    files: KnowledgeDoc[];
-    nextCursor: string | null;
-  }>;
-  readScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string): Promise<{
-    filePath: string;
-    text: string;
-  }>;
-  writeScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string, content: string, opts?: {
-    contentType?: string;
-    message?: string;
-  }): Promise<{
-    filePath: string;
-  }>;
-}
-//# sourceMappingURL=types.d.ts.map
-//#endregion
-export { type KnowledgeApi, type KnowledgeConfig, type KnowledgeDoc, type KnowledgeProfile, type KnowledgeScope, type KnowledgeScopeType, type KnowledgeSearchResult, plugin as default };
-//# sourceMappingURL=index.d.cts.map
+import { a as KnowledgeChangeRequest, c as KnowledgeScope, d as ProposeScopeChangeInput, i as ChangeRequestStatus, l as KnowledgeScopeType, n as KnowledgeApi, o as KnowledgeDoc, r as KnowledgeConfig, s as KnowledgeProfile, t as plugin, u as KnowledgeSearchResult } from "./plugin.cjs";
+export { type ChangeRequestStatus, type KnowledgeApi, type KnowledgeChangeRequest, type KnowledgeConfig, type KnowledgeDoc, type KnowledgeProfile, type KnowledgeScope, type KnowledgeScopeType, type KnowledgeSearchResult, type ProposeScopeChangeInput, plugin as default };

package/dist/index.d.ts

@@ -1,101 +1,2 @@
-import plugin from "./plugin.js";
-
-//#region ../agent-api-client/dist/index.d.ts
-
-type KnowledgeScopeType = "org" | "team" | "project";
-interface KnowledgeScope {
-  scopeType: KnowledgeScopeType;
-  scopeId: string;
-  name: string;
-}
-interface KnowledgeSearchHit {
-  id: string;
-  text: string;
-  /** Normalized relevance in (0,1]; higher = closer. */
-  score: number;
-  scopeType: KnowledgeScopeType;
-  scopeId: string;
-  /**
-   * Provenance of the hit. All live results are `"doc"`; `"fact"` only ever
-   * appears for legacy vectors indexed before the facts primitive was removed
-   * (the search index stays tolerant of them). Treat every hit as a doc.
-   */
-  source: "doc" | "fact";
-  /** The canonical file under shared/<scope>/ (present on doc hits). */
-  filePath?: string;
-  /** Legacy-only: the id of a pre-removal fact vector. */
-  factId?: string;
-}
-interface KnowledgeSearchResult {
-  results: KnowledgeSearchHit[];
-  /** True when fan-out breadth was capped (more member scopes than the cap). */
-  truncatedScopes: boolean;
-}
-interface KnowledgeProfileLink {
-  label: string;
-  url: string;
-}
-interface KnowledgeProfile {
-  scopeType: KnowledgeScopeType;
-  scopeId: string;
-  about: string | null;
-  description: string | null;
-  links: KnowledgeProfileLink[];
-  updatedAt: string | null;
-  updatedBy: string | null;
-}
-interface KnowledgeDoc {
-  filePath: string;
-  fileName: string;
-  contentType?: string;
-  size: number;
-  uploadedBy?: string;
-  createdAt: string;
-  updatedAt: string;
-}
-//#endregion
-//#region src/types.d.ts
-interface KnowledgeConfig {
-  /** Inject org profile + name-only scope list at session start. */
-  injectContext: boolean;
-  /** Cap on scopes listed in the session-start context block. */
-  maxScopes: number;
-}
-/**
- * The subset of `AgentApiClient` the plugin needs. Declaring it as an
- * interface (rather than importing the concrete class everywhere) keeps the
- * injection/formatting code decoupled and unit-testable — the real
- * `AgentApiClient` structurally satisfies it.
- */
-interface KnowledgeApi {
-  knowledgeSearch(query: string, opts?: {
-    limit?: number;
-    scopeType?: KnowledgeScopeType;
-    scopeId?: string;
-  }): Promise<KnowledgeSearchResult>;
-  listScopes(): Promise<{
-    scopes: KnowledgeScope[];
-  }>;
-  getScopeProfile(scopeType: KnowledgeScopeType, scopeId: string): Promise<KnowledgeProfile>;
-  listScopeDocs(scopeType: KnowledgeScopeType, scopeId: string, opts?: {
-    limit?: number;
-    cursor?: string;
-  }): Promise<{
-    files: KnowledgeDoc[];
-    nextCursor: string | null;
-  }>;
-  readScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string): Promise<{
-    filePath: string;
-    text: string;
-  }>;
-  writeScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string, content: string, opts?: {
-    contentType?: string;
-    message?: string;
-  }): Promise<{
-    filePath: string;
-  }>;
-}
-//# sourceMappingURL=types.d.ts.map
-//#endregion
-export { type KnowledgeApi, type KnowledgeConfig, type KnowledgeDoc, type KnowledgeProfile, type KnowledgeScope, type KnowledgeScopeType, type KnowledgeSearchResult, plugin as default };
-//# sourceMappingURL=index.d.ts.map
+import { a as KnowledgeChangeRequest, c as KnowledgeScope, d as ProposeScopeChangeInput, i as ChangeRequestStatus, l as KnowledgeScopeType, n as KnowledgeApi, o as KnowledgeDoc, r as KnowledgeConfig, s as KnowledgeProfile, t as plugin, u as KnowledgeSearchResult } from "./plugin.js";
+export { type ChangeRequestStatus, type KnowledgeApi, type KnowledgeChangeRequest, type KnowledgeConfig, type KnowledgeDoc, type KnowledgeProfile, type KnowledgeScope, type KnowledgeScopeType, type KnowledgeSearchResult, type ProposeScopeChangeInput, plugin as default };

package/dist/plugin.d.cts

@@ -1,70 +1,207 @@
-//#region src/plugin.d.ts
+import { TSchema } from "@sinclair/typebox";
+
+//#region ../agent-api-client/dist/index.d.ts
+
+//# sourceMappingURL=sync.d.ts.map
+//#endregion
+//#region src/domains/knowledge.d.ts
+type KnowledgeScopeType = "org" | "team" | "project";
+interface KnowledgeScope {
+  scopeType: KnowledgeScopeType;
+  scopeId: string;
+  name: string;
+}
+interface KnowledgeSearchHit {
+  id: string;
+  text: string;
+  /** Normalized relevance in (0,1]; higher = closer. */
+  score: number;
+  scopeType: KnowledgeScopeType;
+  scopeId: string;
+  /**
+   * Provenance of the hit. All live results are `"doc"`; `"fact"` only ever
+   * appears for legacy vectors indexed before the facts primitive was removed
+   * (the search index stays tolerant of them). Treat every hit as a doc.
+   */
+  source: "doc" | "fact";
+  /** The canonical file under shared/<scope>/ (present on doc hits). */
+  filePath?: string;
+  /** Legacy-only: the id of a pre-removal fact vector. */
+  factId?: string;
+}
+interface KnowledgeSearchResult {
+  results: KnowledgeSearchHit[];
+  /** True when fan-out breadth was capped (more member scopes than the cap). */
+  truncatedScopes: boolean;
+}
+interface KnowledgeProfileLink {
+  label: string;
+  url: string;
+}
+interface KnowledgeProfile {
+  scopeType: KnowledgeScopeType;
+  scopeId: string;
+  about: string | null;
+  description: string | null;
+  links: KnowledgeProfileLink[];
+  updatedAt: string | null;
+  updatedBy: string | null;
+}
+type ChangeRequestResourceType = "doc" | "profile";
+type ChangeRequestOperation = "create" | "update" | "delete";
+type ChangeRequestStatus = "open" | "approved" | "rejected" | "withdrawn" | "superseded";
+type ChangeRequestActorKind = "human" | "agent";
+/** Public projection of a change request (mirrors `PublicChangeRequest` in services/org). */
+interface KnowledgeChangeRequest {
+  changeRequestId: string;
+  scopeType: KnowledgeScopeType;
+  scopeId: string;
+  resourceType: ChangeRequestResourceType;
+  operation: ChangeRequestOperation;
+  targetPath: string | null;
+  baseVersionId: string | null;
+  proposedContentType: string | null;
+  status: ChangeRequestStatus;
+  proposerId: string;
+  proposerKind: ChangeRequestActorKind;
+  rationale: string;
+  reviewerId: string | null;
+  reviewerKind: ChangeRequestActorKind | null;
+  reviewedAt: string | null;
+  reviewNote: string | null;
+  appliedRef: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+/** Per-type proposal payload for `proposeScopeChange`. */
+interface ProposeScopeChangeInput {
+  resourceType: ChangeRequestResourceType;
+  operation: ChangeRequestOperation;
+  /** Why the change is proposed — shown to the reviewer. */
+  rationale: string;
+  /** doc: the path the proposal applies to (e.g. designs/data-center.md). */
+  targetPath?: string;
+  /** doc create/update: the staged body to upload (markdown or other text). */
+  content?: string;
+  /** doc create/update: content type of the staged body (default text/markdown). */
+  contentType?: string;
+  /** profile: the proposed value ({ about, description, links }). */
+  proposedValue?: unknown;
+}
+interface KnowledgeDoc {
+  filePath: string;
+  fileName: string;
+  contentType?: string;
+  size: number;
+  uploadedBy?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+//#endregion
+//#region ../openclaw-plugin-kit/dist/index.d.ts
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/tools.d.ts
+/** Shape returned to OpenClaw from a tool `execute`. */
+interface ToolResult {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  details: unknown;
+  isError?: boolean;
+}
+interface ToolDef<TParameters = unknown> {
+  name: string;
+  description: string;
+  label: string;
+  parameters: TParameters;
+  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
+//#endregion
+//#region src/types.d.ts
+interface KnowledgeConfig {
+  /** Inject org profile + name-only scope list at session start. */
+  injectContext: boolean;
+  /** Cap on scopes listed in the session-start context block. */
+  maxScopes: number;
+}
 /**
- * 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.
- *
- * Shared knowledge is curated DOCUMENTS (+ scope profiles). There is no
- * free-floating "fact" primitive: an agent that learns something durable
- * finds the right document and edits it in (search → read_doc → write_doc /
- * propose_change). Quick or uncertain capture belongs in the agent's private
- * per-agent memory, not shared knowledge.
- *
- * Backed by:
- * - services/knowledge — RAG search (vector index over docs)
- * - services/org       — system of record + per-agent membership gate
- *                        (docs, profile)
- *
- * Registers:
- * - Tools: resource_search, resource_read_doc, resource_write_doc,
- *   resource_get_profile, resource_list_scopes,
- *   resource_propose_change, resource_list_change_requests
- * - Lifecycle hook: before_agent_start (bounded org-profile + scope-list inject)
- *
- * NOTE: every tool name here MUST also appear in `openclaw.plugin.json`'s
- * `contracts.tools` allowlist — OpenClaw (2026.5+) gates the model's tool
- * payload on that strict-literal list, so a registered-but-unlisted tool is
- * invisible to the LLM.
+ * The subset of `AgentApiClient` the plugin needs. Declaring it as an
+ * interface (rather than importing the concrete class everywhere) keeps the
+ * injection/formatting code decoupled and unit-testable — the real
+ * `AgentApiClient` structurally satisfies it.
  */
+interface KnowledgeApi {
+  knowledgeSearch(query: string, opts?: {
+    limit?: number;
+    scopeType?: KnowledgeScopeType;
+    scopeId?: string;
+  }): Promise<KnowledgeSearchResult>;
+  listScopes(): Promise<{
+    scopes: KnowledgeScope[];
+  }>;
+  getScopeProfile(scopeType: KnowledgeScopeType, scopeId: string): Promise<KnowledgeProfile>;
+  listScopeDocs(scopeType: KnowledgeScopeType, scopeId: string, opts?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<{
+    files: KnowledgeDoc[];
+    nextCursor: string | null;
+  }>;
+  readScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string, opts?: {
+    maxBytes?: number;
+  }): Promise<{
+    filePath: string;
+    text: string;
+  }>;
+  writeScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string, content: string, opts?: {
+    contentType?: string;
+    message?: string;
+  }): Promise<{
+    filePath: string;
+  }>;
+  proposeScopeChange(scopeType: KnowledgeScopeType, scopeId: string, input: ProposeScopeChangeInput): Promise<KnowledgeChangeRequest>;
+  listScopeChangeRequests(scopeType: KnowledgeScopeType, scopeId: string, opts?: {
+    status?: ChangeRequestStatus;
+    limit?: number;
+    cursor?: string;
+  }): Promise<{
+    changeRequests: KnowledgeChangeRequest[];
+    nextCursor: string | null;
+  }>;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/runtime.d.ts
+interface PluginLogger {
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+}
 interface PluginApi {
-  pluginConfig?: Record<string, unknown>;
-  config: Record<string, unknown>;
-  logger: {
-    info: (msg: string, ctx?: Record<string, unknown>) => void;
-    debug: (msg: string, ctx?: Record<string, unknown>) => void;
-    warn: (msg: string, ctx?: Record<string, unknown>) => void;
-    error: (msg: string, ctx?: Record<string, unknown>) => void;
-  };
-  registerTool: (factory: (ctx: ToolContext) => Tool, opts?: {
+  pluginConfig?: unknown;
+  logger: PluginLogger;
+  registerTool(tool: ToolDef<TSchema>, options?: {
     names?: string[];
-  }) => void;
-  on: (hookName: string, handler: (...args: unknown[]) => unknown, opts?: {
+  }): void;
+  on(hookName: string, handler: (...args: unknown[]) => unknown, options?: {
     priority?: number;
-  }) => void;
+  }): void;
 }
-interface ToolContext {
-  agentId?: string;
-  sessionKey?: string;
-  sessionId?: string;
-  messageChannel?: string;
-}
-interface Tool {
-  name: string;
-  label: string;
-  description: string;
-  parameters: Record<string, unknown>;
-  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<unknown>;
-}
-declare const plugin: {
+interface KnowledgePlugin {
   id: string;
   name: string;
   description: string;
   version: string;
-  register(api: PluginApi): void;
-};
+  activate(api: PluginApi): void;
+  deactivate(api: PluginApi): void;
+}
+//#endregion
+//#region src/plugin.d.ts
+declare const plugin: KnowledgePlugin;
 //#endregion
-export { plugin as default };
+export { KnowledgeChangeRequest as a, KnowledgeScope as c, ProposeScopeChangeInput as d, ChangeRequestStatus as i, KnowledgeScopeType as l, KnowledgeApi as n, KnowledgeDoc as o, KnowledgeConfig as r, KnowledgeProfile as s, plugin as t, KnowledgeSearchResult as u };
 //# sourceMappingURL=plugin.d.cts.map