@unblocklabs/unblock-memory 0.3.16 → 0.3.18

package/README.md

@@ -524,18 +524,105 @@ directory.
 
 ### People Whisperer
 
+#### Optional People Dossier Primer
+
+`memory_people_prime({ personId, agentName? })` prepares evidence for an existing person;
+it does **not** generate claims, update dossiers, or inject context. With
+`people.enabled: true`, opt in separately:
+
+```json
+{
+  "peoplePrimer": {
+    "enabled": true,
+    "corpora": ["memory", "knowledge", "sessions"],
+    "hitsPerQuestion": 30,
+    "minScore": 0.35,
+    "minUsefulness": 0.8,
+    "maxEvidencePerQuestion": 3,
+    "timeoutMs": 30000
+  }
+}
+```
+
+List only configured, approved non-skill corpora. The feature is **off by
+default** and requires shared TypeSafe credentials. Disabled TypeSafe or missing/
+unreadable credentials safely skip the primer; agents can still research normally.
+Enabling it approves sending the person's identity, retrieved excerpts and optional
+draft snippet to TypeSafe. Existing dossiers are not sent as grading evidence.
+Sessions includes all indexed conversations;
+results are available to the agent's tool callers, so scope approval accordingly.
+
+Three default questions cover explicit role/organization, enduring organizational
+background, and the person's relationship to the agent (not its business mission).
+Preferences, working styles, priorities, feedback and task history are excluded.
+Each uses QMD vector search (no query expansion) for up to 30 hits, configurable
+up to 40. All unique eligible hits above the vector threshold are graded, not just
+the final top three. Complete excerpts over 6,000 characters are counted and skipped,
+not silently truncated. Duplicate source spans across questions share a request;
+Independent attribution, explicit-background, durability, recognition-value and
+question-usefulness judgments run together; every dimension must pass the threshold.
+Every candidate is graded against all three questions, regardless of which search
+found it. Mixed excerpts may supply a useful background fact without making their
+surrounding behavioral content eligible for the snippet.
+Provider concurrency is four, with a two-minute overall tool deadline.
+
+Supply the agent's human-facing name when no identity name is configured; otherwise
+questions use "the assistant", never an internal routing ID such as `main`.
+The output includes a deduplicated source-linked excerpt list referenced by each
+question's evidence IDs, a bounded uncertain-review shortlist,
+and retrieval/cache/failure counts. Coverage is `evidence_found`, `uncertain` or
+`unknown`, not a claim that a question has been definitively answered. Partial
+provider failures are explicit; absence of selected hits does not prove absence of
+evidence. The agent must verify dates, speakers and contradictions before writing.
+Memory evidence never grants permissions or establishes that an old request is
+still open.
+
+`memory_people_update({ action: "replace_dossier", personId, dossier, reason,
+agentName? })` automatically checks the proposed blurb before saving. Exact
+`qmd://path#Lstart-Lend` claim evidence locators supply up to three indexed ranges
+from the primer's approved corpora (120 lines each, 6,000 characters total).
+Support confidence and background-only/explicit-support probabilities must all
+be >=0.9. `needs_review` or `review_unavailable` leaves the dossier and history
+unchanged; missing keys and failures never count as approval. A concurrent dossier
+edit/deletion returns `conflict` instead of overwriting the newer change.
+
+After independently verifying every assertion and background eligibility, an agent
+can supply a source-specific `manualVerification` explanation (up to 400 characters)
+for direct human corrections, non-indexed evidence or disabled/unavailable/incorrect
+reviews. This explicit path skips TypeSafe, records manual provenance in change
+history and keeps all structural limits. It is not a provider pass. Normal success
+returns `status: "ok"`, `saved: true` and `verification: "typesafe" | "manual"`.
+The skill documents when to use each path. Sources outside approved corpora are
+rejected before egress; no separate `evidenceReview` toggle is needed.
+
+For optional read-only diagnostics, `memory_people_prime({ personId, agentName?,
+draft: { blurb, citations: [{ path, from, lines }] } })` still reviews a snippet
+without writing. Agents do not need this extra call in the normal update workflow.
+
+Judgments are cached privately in `people.sqlite` (maximum 2,000 entries), keyed
+by person, agent, exact evidence/context, questions,
+and judge version. No source text or credentials are stored in the cache.
+Retrieval reruns against the current index; unchanged judgments are reused.
+This is on-demand preparation, not a new scheduler or incremental session scanner.
+Use it from an existing People Whisperer maintenance cron. Refresh stale session
+indexes with `memory_sync_sessions` before priming when needed.
+
+#### People store and maintenance
+
 PeopleSQL is an optional agent-local people store. When `people.enabled` is
 true, incoming Slack messages with a canonical agent session key and exact
 account and sender IDs create or refresh an injection-enabled person record.
 Incomplete Slack identities create a bounded, deduplicated todo without storing
 message content. Other channels are ignored.
 
-PeopleSQL registers three tools when enabled:
+PeopleSQL registers these tools when enabled:
 
 - `memory_people_inspect` lists active people, reads one exact person, reads one
   person's dossier change history, or lists bounded actionable todos;
 - `memory_people_update` replaces or deletes dossiers, toggles one person's
-  injection, and manages company, todo, deletion, or restoration state; and
+  injection, and manages company, todo, deletion, or restoration state;
+- `memory_people_prime` prepares evidence when the separately opted-in primer is
+  enabled, otherwise returns disabled; and
 - the optional `memory_people_sync` enriches one active OpenClaw Slack account;
   its tool input accepts an account ID, not a token.
 
@@ -551,10 +638,18 @@ person's current dossier, search ordinary memory and sessions with
 `memory_search`/`memory_get`, and replace the dossier when that would improve a
 future conversation. The plugin owns no dossier-maintenance workflow or refresh
 schedule. A dossier's `reviewedAt` value records its last successful write; it
-is not scheduling state. The plugin performs no model call for dossier
-maintenance or prompt injection.
-
-Every `replace_dossier` and `delete_dossier` action requires a concise `reason`.
+is not scheduling state. Dossier generation belongs to the agent; prompt injection
+performs no model call. The optional primer grades evidence and reviews draft snippets.
+The goal is recognition, not a behavioral profile: one short paragraph of at most
+70 words identifying the person and their enduring organization/agent relationship.
+New writes allow only `role`/`relationship` sections and explicit `observed`/`reported`
+claims; priorities, preferences and inferred profiles belong outside dossiers.
+Legacy dossiers remain readable, but must be deliberately rewritten by the agent
+before replacement. No automatic destructive migration or blanket deletion occurs.
+
+Every `replace_dossier` and `delete_dossier` action requires a concise `reason`
+(up to 500 characters for replacements, 1,000 for deletions). Replacement history
+also records whether TypeSafe checks passed or a manual attestation was used.
 The plugin transactionally records that reason with its authoritative before and
 after dossier snapshots. List small newest-first summaries with
 `memory_people_inspect({ view: "dossier_changes", personId, limit?, offset? })`,
@@ -577,20 +672,15 @@ The package includes a `$people-whisperer` skill with the canonical agent
 procedure and dossier shape. For a manual refresh, ask:
 
 ```text
-Use $people-whisperer to improve your understanding of this person. Search memory
-and recent sessions, inspect their current PeopleSQL dossier, and update it only
-if the result would make future conversations meaningfully better.
+Use $people-whisperer to maintain this person's brief background snippet.
 ```
 
 For an optional cron or isolated agent session, use this goal:
 
 ```text
-Use $people-whisperer to improve your understanding of people you interact with.
-
-Search recent sessions and memory for meaningful information about people. Inspect
-their existing PeopleSQL dossiers when useful. Update a dossier only when doing so
-would make future conversations meaningfully better. Ignore routine conversation,
-repetition, and weak inference. You may update several people or nobody.
+Use $people-whisperer to maintain brief background snippets for people you interact
+with. Follow the packaged skill, including source verification and write results.
+Update only when useful; several people or nobody is fine. Report changes and gaps.
 ```
 
 Choose any cadence appropriate for the agent; the plugin does not require or
@@ -641,12 +731,12 @@ session manifest. The projected file modification time matches the session
 start time for meaningful chronological cluster reads. Session results include
 provider, chat type, conversation identity, and start time as an ISO 8601 timestamp. They
 participate in the same search and clustering index as file memory. The plugin
-automatically refreshes each configured agent's sessions every 15 minutes while
+automatically checks each configured agent's sessions every 60 minutes while
 the Gateway runs. Set `syncIntervalMinutes` on the `sessions` corpus to an integer
 from `1` to `1440`, or `0` for manual-only syncing. For example:
 
 ```json
-{ "name": "sessions", "kind": "sessions", "syncIntervalMinutes": 15 }
+{ "name": "sessions", "kind": "sessions", "syncIntervalMinutes": 60 }
 ```
 
 The first refresh runs after one interval, not during startup. Restart the
@@ -655,6 +745,17 @@ sync is skipped, and failures are visible through `memory_sync_status` and retri
 at the next interval. `memory_sync_sessions` still provides an immediate manual
 refresh. Syncing and embedding run inside the Gateway process, without an LLM turn.
 
+Quiet checks compare source metadata and the last successful index checkpoint
+before initializing the memory manager. Unchanged sessions skip QMD updates and
+embedding. New assistant answers count too, not just human messages. Changed
+transcripts are projected and content-hashed; tool-only or filtered additions
+that leave the indexed text unchanged also skip indexing. Empty/filtered sessions
+are remembered. Index changes, missing projections, changed projection settings,
+QMD upgrades and incomplete runs invalidate the skip checkpoint; `force: true`
+bypasses both gates. `memory_sync_status` reports `lastCheckedAt`, `lastIndexedAt`
+and `skipReason` (`no_changes` or `no_indexable_changes`) separately. Existing
+explicit intervals remain unchanged on upgrade; set them to `60` for hourly checks.
+
 Indexes live at `~/.openclaw/agents/<agentId>/unblock-memory/index.sqlite` (or the
 equivalent configured OpenClaw state directory). Durable agent-supplied event
 dates and maintenance proposals live separately in `curation.sqlite`, so a QMD

package/dist/src/config.d.ts

@@ -1,4 +1,5 @@
 import { type ResponseAuditConfig } from "./response-config.js";
+import { type PeoplePrimerConfig } from "./people-primer-config.js";
 export type FileCorpusConfig = {
     name: string;
     kind: "files";
@@ -42,6 +43,7 @@ export type UnblockMemoryConfig = {
         corpora: readonly string[];
     };
     responseAudit: ResponseAuditConfig;
+    peoplePrimer: PeoplePrimerConfig;
     people: {
         enabled: boolean;
         whisperer: {

package/dist/src/config.js

@@ -1,5 +1,6 @@
 import { isAbsolute } from "node:path";
 import { resolveResponseAudit } from "./response-config.js";
+import { resolvePeoplePrimer } from "./people-primer-config.js";
 const DEFAULT_PATHS = ["MEMORY.md", "USER.md", "memory/**/*.md"];
 const DEFAULT_SESSION_MAX_EXPANDED_TOKENS = 500;
 const MAX_SESSION_MAX_EXPANDED_TOKENS = 10_000;
@@ -171,7 +172,7 @@ function resolveCorpora(value) {
                 !chatTypes.every((chatType) => CHAT_TYPES.includes(chatType))) {
                 throw new Error(`unblock-memory corpus sessions chatTypes must contain channel, group, or direct`);
             }
-            const syncIntervalMinutes = corpus.syncIntervalMinutes ?? 15;
+            const syncIntervalMinutes = corpus.syncIntervalMinutes ?? 60;
             if (typeof syncIntervalMinutes !== "number" || !Number.isInteger(syncIntervalMinutes) ||
                 syncIntervalMinutes < 0 || syncIntervalMinutes > 1440) {
                 throw new Error("unblock-memory corpus sessions syncIntervalMinutes must be an integer between 0 and 1440");
@@ -264,6 +265,7 @@ export function resolveConfig(value) {
             qualityAudit: { ...DEFAULT_QUALITY_AUDIT },
             evidenceReview: { enabled: false, corpora: [] },
             responseAudit: resolveResponseAudit(undefined, DEFAULT_CORPORA),
+            peoplePrimer: resolvePeoplePrimer(undefined, DEFAULT_CORPORA, false),
             people: DEFAULT_PEOPLE_CONFIG,
             skillWhisperer: DEFAULT_SKILL_WHISPERER,
             memoryWhisperer: { ...DEFAULT_MEMORY_WHISPERER },
@@ -273,9 +275,10 @@ export function resolveConfig(value) {
         throw new Error("unblock-memory config must be an object");
     }
     const config = value;
-    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "skillWhisperer", "memoryWhisperer", "typesafe", "qualityAudit", "evidenceReview", "responseAudit"], "config");
+    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "peoplePrimer", "skillWhisperer", "memoryWhisperer", "typesafe", "qualityAudit", "evidenceReview", "responseAudit"], "config");
     const corpora = resolveCorpora(config.corpora);
     const people = resolvePeople(config.people);
+    const peoplePrimer = resolvePeoplePrimer(config.peoplePrimer, corpora, people.enabled);
     let evidenceReview = { enabled: false, corpora: [] };
     if (config.evidenceReview !== undefined) {
         const value = config.evidenceReview;
@@ -346,7 +349,7 @@ export function resolveConfig(value) {
     if (skillWhisperer.enabled && !corpora.some((corpus) => corpus.kind === "skills")) {
         throw new Error('unblock-memory enabled skillWhisperer requires a corpus named "skills" with kind "skills"');
     }
-    return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, people, skillWhisperer,
+    return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, people, peoplePrimer, skillWhisperer,
         qualityAudit: resolveQualityAudit(config.qualityAudit, corpora),
         evidenceReview,
         responseAudit: resolveResponseAudit(config.responseAudit, corpora),

package/dist/src/evidence-review.d.ts

@@ -13,6 +13,10 @@ export declare function reviewIndexedClaim(params: {
     apiKey: string;
     timeoutMs: number;
     signal: AbortSignal;
+    personBackground?: {
+        name: string;
+        agentName: string;
+    };
     read?: <T>(run: () => T) => Promise<T>;
 }): Promise<{
     status: "unavailable";
@@ -29,6 +33,11 @@ export declare function reviewIndexedClaim(params: {
     }[];
     policy: string;
     scope: string;
+    needsReview: boolean;
+    background?: {
+        backgroundOnly: number;
+        explicitSupport: number;
+    } | undefined;
     verdict: "supports" | "contradicts" | "insufficient_evidence";
     confidence: number;
     probabilities: {
@@ -36,6 +45,5 @@ export declare function reviewIndexedClaim(params: {
         contradicts: number;
         insufficient_evidence: number;
     };
-    needsReview: boolean;
     status: "ok";
 }>;

package/dist/src/evidence-review.js

@@ -45,6 +45,7 @@ export async function reviewIndexedClaim(params) {
         }
         return { status: "ok", ...judgment,
             evidence: evidence.map(({ text: _text, ...citation }) => citation),
-            policy: "jev-1.13.0:claim-v1", scope: "Advisory support check against cited indexed excerpts only, not current truth or authorization to write. Verify original sources and identity before promotion." };
+            policy: params.personBackground ? "jev-1.13.0:person-background-v2" : "jev-1.13.0:claim-v1",
+            scope: "Advisory support check against cited indexed excerpts only, not current truth or authorization to write. Verify original sources and identity before promotion." };
     });
 }

package/dist/src/manager.d.ts

@@ -85,6 +85,11 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         }[];
         policy: string;
         scope: string;
+        needsReview: boolean;
+        background?: {
+            backgroundOnly: number;
+            explicitSupport: number;
+        } | undefined;
         verdict: "supports" | "contradicts" | "insufficient_evidence";
         confidence: number;
         probabilities: {
@@ -92,7 +97,6 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
             contradicts: number;
             insufficient_evidence: number;
         };
-        needsReview: boolean;
         status: "ok";
     }>;
     reviewCluster(params: Omit<Parameters<typeof reviewClusterIngestion>[0], "db" | "sources" | "read"> & {

package/dist/src/manager.js

@@ -534,12 +534,14 @@ export class QmdMemoryManager {
             if (!sessions)
                 throw new Error('memory session sync requires a configured "sessions" corpus');
             onPhase?.("projecting");
-            const store = await this.#getStore();
             const synced = await syncSessionProjections({
                 ...sessions,
                 force,
+                indexPath: this.#dbPath,
+                indexReady: async () => (await (await this.#getStore()).getStatus()).needsEmbedding === 0,
                 index: async () => {
                     onPhase?.("indexing");
+                    const store = await this.#getStore();
                     const update = await store.update({ collections: [sessions.collection] });
                     this.#cleanupRemovedDocuments?.(update.updated + update.removed);
                     const analysisStore = store;
@@ -561,6 +563,9 @@ export class QmdMemoryManager {
                 },
             });
             this.#sessionMetadata = sessionMetadataByPath(synced.manifest);
+            if (synced.result.skipReason)
+                return synced.result;
+            const store = await this.#getStore();
             const status = await store.getStatus();
             const collections = await store.listCollections();
             this.#files = collections.reduce((total, collection) => total + collection.active_count, 0);

package/dist/src/people-background.d.ts

@@ -0,0 +1,3 @@
+/** A recognition aid, never a behavioral profile. Existing records remain readable. */
+export declare const PEOPLE_BACKGROUND_MAX_WORDS = 70;
+export declare function backgroundWordCount(text: string): number;

package/dist/src/people-background.js

@@ -0,0 +1,5 @@
+/** A recognition aid, never a behavioral profile. Existing records remain readable. */
+export const PEOPLE_BACKGROUND_MAX_WORDS = 70;
+export function backgroundWordCount(text) {
+    return text.trim().split(/\s+/u).filter(Boolean).length;
+}

package/dist/src/people-dossier-review.d.ts

@@ -0,0 +1,41 @@
+import type { UnblockMemoryConfig } from "./config.js";
+import type { Person, PersonDossier } from "./people-store.js";
+import type { QmdMemoryRuntime } from "./runtime.js";
+import type { getContext } from "./tool-context.js";
+/** Review the injected blurb using only exact indexed references already on its claims. */
+export declare function reviewPersonDossier(params: {
+    config: UnblockMemoryConfig;
+    runtime: QmdMemoryRuntime;
+    active: NonNullable<ReturnType<typeof getContext>>;
+    person: Person;
+    dossier: PersonDossier;
+    agentName?: string;
+    signal?: AbortSignal;
+}): Promise<{
+    evidence: {
+        path: string;
+        from: number;
+        lines: number;
+        documentHash: string;
+        excerptHash: string;
+    }[];
+    policy: string;
+    scope: string;
+    needsReview: boolean;
+    background?: {
+        backgroundOnly: number;
+        explicitSupport: number;
+    } | undefined;
+    verdict: "supports" | "contradicts" | "insufficient_evidence";
+    confidence: number;
+    probabilities: {
+        supports: number;
+        contradicts: number;
+        insufficient_evidence: number;
+    };
+    status: "ok";
+} | {
+    status: "unavailable";
+    needsReview: boolean;
+    reason: string;
+}>;

package/dist/src/people-dossier-review.js

@@ -0,0 +1,47 @@
+import { resolveAgentIdentity } from "openclaw/plugin-sdk/agent-runtime";
+import { abortable } from "./abortable.js";
+import { resolveTypeSafeApiKey } from "./typesafe.js";
+/** Review the injected blurb using only exact indexed references already on its claims. */
+export async function reviewPersonDossier(params) {
+    const unavailable = (reason) => ({ status: "unavailable", needsReview: true, reason });
+    const { config, runtime, active, person, dossier } = params;
+    if (!config.peoplePrimer.enabled || !config.typesafe.enabled) {
+        return unavailable("TypeSafe background review is disabled; verify manually before saving");
+    }
+    const citations = new Map();
+    for (const section of dossier.sections)
+        for (const claim of section.claims)
+            for (const ref of claim.evidence) {
+                const match = /^(qmd:\/\/[^#]+)#L([1-9]\d*)(?:-L([1-9]\d*))?$/.exec(ref.locator);
+                if (!match)
+                    return unavailable("Evidence needs exact qmd://path#Lstart-Lend references or explicit manual verification");
+                const from = Number(match[2]), end = Number(match[3] ?? match[2]);
+                if (!Number.isSafeInteger(from) || !Number.isSafeInteger(end) || end < from || end - from >= 120) {
+                    return unavailable("Evidence ranges must contain 1–120 lines");
+                }
+                const citation = { path: match[1], from, lines: end - from + 1 };
+                citations.set(JSON.stringify(citation), citation);
+            }
+    if (!citations.size || citations.size > 3)
+        return unavailable("Choose 1–3 distinct indexed evidence ranges or verify manually");
+    const deadline = AbortSignal.timeout(120_000);
+    const signal = params.signal ? AbortSignal.any([params.signal, deadline]) : deadline;
+    try {
+        signal.throwIfAborted();
+        const apiKey = await abortable(resolveTypeSafeApiKey(config.typesafe), signal);
+        if (!apiKey)
+            return unavailable("TypeSafe API key not configured; verify manually before saving");
+        const { manager } = await abortable(runtime.getMemorySearchManager(active), signal);
+        if (!manager)
+            return unavailable("Memory index unavailable; verify manually before saving");
+        return await abortable(manager.reviewClaim({
+            claim: dossier.blurb, citations: [...citations.values()],
+            personBackground: { name: person.preferredName ?? person.displayName,
+                agentName: resolveAgentIdentity(active.cfg, active.agentId)?.name?.trim() || params.agentName?.trim() || "the assistant" },
+            corpora: config.peoplePrimer.corpora, apiKey, timeoutMs: config.peoplePrimer.timeoutMs, signal,
+        }), signal);
+    }
+    catch {
+        return unavailable("Background review failed or was cancelled; no dossier written");
+    }
+}

package/dist/src/people-primer-config.d.ts

@@ -0,0 +1,13 @@
+import { Type, type Static } from "typebox";
+import type { CorpusConfig } from "./config.js";
+export declare const peoplePrimerSchema: Type.TObject<{
+    enabled: Type.TBoolean;
+    corpora: Type.TArray<Type.TString>;
+    hitsPerQuestion: Type.TInteger;
+    minScore: Type.TNumber;
+    minUsefulness: Type.TNumber;
+    maxEvidencePerQuestion: Type.TInteger;
+    timeoutMs: Type.TInteger;
+}>;
+export type PeoplePrimerConfig = Static<typeof peoplePrimerSchema>;
+export declare function resolvePeoplePrimer(value: unknown, corpora: readonly CorpusConfig[], peopleEnabled: boolean): PeoplePrimerConfig;

package/dist/src/people-primer-config.js

@@ -0,0 +1,33 @@
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+export const peoplePrimerSchema = Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    corpora: Type.Array(Type.String({ minLength: 1 }), { default: [] }),
+    hitsPerQuestion: Type.Integer({ minimum: 1, maximum: 40, default: 30 }),
+    minScore: Type.Number({ minimum: 0, maximum: 1, default: 0.35 }),
+    minUsefulness: Type.Number({ minimum: 0.5, maximum: 1, default: 0.8 }),
+    maxEvidencePerQuestion: Type.Integer({ minimum: 1, maximum: 10, default: 3 }),
+    timeoutMs: Type.Integer({ minimum: 1, maximum: 60000, default: 30000 }),
+}, { additionalProperties: false });
+export function resolvePeoplePrimer(value, corpora, peopleEnabled) {
+    if (value === undefined)
+        return { enabled: false, corpora: [], hitsPerQuestion: 30,
+            minScore: 0.35, minUsefulness: 0.8, maxEvidencePerQuestion: 3, timeoutMs: 30000 };
+    let config;
+    try {
+        const withDefaults = Value.Default(peoplePrimerSchema, value);
+        if (!Value.Check(peoplePrimerSchema, withDefaults))
+            throw new Error("Invalid config");
+        config = withDefaults;
+    }
+    catch {
+        throw new Error("Invalid peoplePrimer configuration");
+    }
+    if (config.corpora.some(name => !corpora.some(c => c.name === name && c.kind !== "skills"))) {
+        throw new Error("peoplePrimer.corpora must list configured non-skill corpora");
+    }
+    if (config.enabled && (!peopleEnabled || !config.corpora.length)) {
+        throw new Error("peoplePrimer requires people.enabled and explicit approved corpora");
+    }
+    return { ...config, corpora: [...new Set(config.corpora)] };
+}

package/dist/src/people-primer-tool.d.ts

@@ -0,0 +1,5 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { UnblockMemoryConfig } from "./config.js";
+import type { PeopleStores } from "./people-store.js";
+import type { QmdMemoryRuntime } from "./runtime.js";
+export declare function registerPeoplePrimerTool(api: OpenClawPluginApi, runtime: QmdMemoryRuntime, stores: PeopleStores, config: UnblockMemoryConfig): void;

package/dist/src/people-primer-tool.js

@@ -0,0 +1,78 @@
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { jsonResult, resolveAgentIdentity } from "openclaw/plugin-sdk/agent-runtime";
+import { getContext } from "./tool-context.js";
+import { resolveTypeSafeApiKey } from "./typesafe.js";
+import { primePersonDossier } from "./people-primer.js";
+import { abortable } from "./abortable.js";
+import { backgroundWordCount, PEOPLE_BACKGROUND_MAX_WORDS } from "./people-background.js";
+const parameters = Type.Object({
+    personId: Type.String({ pattern: "\\S", maxLength: 1000 }),
+    agentName: Type.Optional(Type.String({ pattern: "\\S", maxLength: 100,
+        description: "Your human-facing name, e.g. Bill, when no agent identity name is configured. Never a person's name guessed from search results." })),
+    draft: Type.Optional(Type.Object({
+        blurb: Type.String({ pattern: "\\S", maxLength: 1200, description: "Final background-only snippet, at most 70 words. Supplying a draft reviews it instead of running searches." }),
+        citations: Type.Array(Type.Object({
+            path: Type.String({ pattern: "^qmd://", maxLength: 2000 }),
+            from: Type.Integer({ minimum: 1 }), lines: Type.Integer({ minimum: 1, maximum: 120 }),
+        }, { additionalProperties: false }), { minItems: 1, maxItems: 3 }),
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
+export function registerPeoplePrimerTool(api, runtime, stores, config) {
+    const running = new Set();
+    api.registerTool(ctx => {
+        const active = getContext(ctx);
+        if (!active)
+            return null;
+        return {
+            name: "memory_people_prime", label: "Prime Person Dossier",
+            description: "Prepare background-only evidence using three identity/organization/agent-relationship questions. Supply draft to review a final <=70-word snippet against indexed citations instead of searching. Requires peoplePrimer opt-in and approved corpora. Sends identity, approved excerpts and optional draft to TypeSafe, never the existing dossier. Advisory; never writes dossiers.",
+            parameters,
+            async execute(_id, params, signal) {
+                const { personId, agentName: suppliedName, draft } = Value.Parse(parameters, params);
+                if (!config.people.enabled || !config.peoplePrimer.enabled || !config.typesafe.enabled)
+                    return jsonResult({ status: "disabled" });
+                if (draft && backgroundWordCount(draft.blurb) > PEOPLE_BACKGROUND_MAX_WORDS) {
+                    return jsonResult({ status: "invalid", needsReview: true, reason: "Background snippet must not exceed 70 words" });
+                }
+                const key = JSON.stringify([active.agentId, personId]);
+                if (running.has(key))
+                    return jsonResult({ status: "busy" });
+                running.add(key);
+                const deadline = AbortSignal.timeout(120_000);
+                const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+                try {
+                    combined.throwIfAborted();
+                    const apiKey = await abortable(resolveTypeSafeApiKey(config.typesafe), combined);
+                    combined.throwIfAborted();
+                    if (!apiKey)
+                        return jsonResult({ status: "unavailable", reason: "TypeSafe API key not configured" });
+                    const store = stores.get(active.agentId);
+                    const person = store.getPerson(personId);
+                    if (!person || person.status !== "active")
+                        return jsonResult({ status: "not_found" });
+                    const identities = store.listIdentities(personId);
+                    if (identities.length && identities.every(i => i.isBot === true || i.isDeactivated))
+                        return jsonResult({ status: "unavailable", reason: "No active human identity" });
+                    const { manager } = await abortable(runtime.getMemorySearchManager(active), combined);
+                    combined.throwIfAborted();
+                    if (!manager)
+                        return jsonResult({ status: "unavailable", reason: "Memory unavailable" });
+                    const agentName = resolveAgentIdentity(active.cfg, active.agentId)?.name?.trim() || suppliedName?.trim() || "the assistant";
+                    if (draft)
+                        return jsonResult(await manager.reviewClaim({ claim: draft.blurb, citations: draft.citations,
+                            personBackground: { name: person.preferredName ?? person.displayName, agentName },
+                            corpora: config.peoplePrimer.corpora, apiKey, timeoutMs: config.peoplePrimer.timeoutMs, signal: combined }));
+                    return jsonResult(await primePersonDossier({ personId, agentName, store, config: config.peoplePrimer, apiKey, signal: combined,
+                        search: (query, options) => manager.search(query, { ...options, requestContext: active.requestContext }) }));
+                }
+                catch {
+                    return jsonResult({ status: "unavailable", needsReview: true, reason: "Primer failed or was cancelled; no dossier written" });
+                }
+                finally {
+                    running.delete(key);
+                }
+            },
+        };
+    }, { names: ["memory_people_prime"] });
+}