@bizagent/dsh 0.0.0-stage → 1.0.0

package/lib/session-surface.d.ts

@@ -0,0 +1,11 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { BizAgentService } from './service.js';
+import type { UiAgentRuntime, UiSessionActivity, UiSessionContext, UiSessionSummary } from './ui-contract.js';
+type Runtime = (sessionId: string) => UiAgentRuntime;
+/** Lightweight sidebar data: no transcript reads and no creation of new Home bindings. */
+export declare function sessionCatalog(service: BizAgentService, runtime: Runtime): UiSessionSummary[];
+export declare function sessionContext(service: BizAgentService, sessionId: string, cwd: string | undefined, events: readonly SessionEvent[], runtime: Runtime): Promise<UiSessionContext>;
+/** Project successful durable results only; a tool call alone is never evidence of success. */
+export declare function sessionActivity(events: readonly SessionEvent[]): UiSessionActivity[];
+export {};
+//# sourceMappingURL=session-surface.d.ts.map

package/lib/session-surface.js

@@ -0,0 +1,109 @@
+import { principalSessionId, projectMainSessionId } from './agent-session-address.js';
+/** Lightweight sidebar data: no transcript reads and no creation of new Home bindings. */
+export function sessionCatalog(service, runtime) {
+    const works = service.workLedger?.list() ?? [];
+    const projects = service.projectLedger?.list() ?? [];
+    const learning = new Set(service.ledger.listLearningLaunches().map(item => item.workerSessionId));
+    const mains = new Map(projects.map(project => [projectMainSessionId(project.id), project]));
+    return service.ledger.listBindings().filter(binding => service.store.hasHome(binding.homeAddress)).map(binding => {
+        const home = service.store.getHome(binding.homeAddress);
+        const work = works.find(item => item.workerSessionId === binding.sessionId && item.assignee === home.address);
+        const main = mains.get(binding.sessionId);
+        const project = main ?? projects.find(item => item.id === work?.projectId);
+        return {
+            sessionId: binding.sessionId,
+            home: { address: home.address, displayName: home.displayName,
+                scope: service.store.isPersonalHome(home.address) ? 'personal' : 'organization' },
+            runtime: runtime(binding.sessionId),
+            kind: work ? 'work' : main ? 'project-main' : learning.has(binding.sessionId) ? 'learning'
+                : service.ledger.getInboxWakeOrigin(binding.sessionId) ? 'inbox'
+                    : principalSessionId(home.address) === binding.sessionId ? 'principal' : 'conversation',
+            ...(work ? { workId: work.id, workGoal: work.goal, workStatus: work.status } : {}),
+            ...(project ? { projectId: project.id, projectTitle: project.title } : {}),
+        };
+    });
+}
+export async function sessionContext(service, sessionId, cwd, events, runtime) {
+    const frames = await service.frameStatusForSession(sessionId, cwd, events);
+    const summary = sessionCatalog(service, runtime).find(item => item.sessionId === sessionId);
+    if (!summary)
+        throw new Error('Session has no available Home');
+    const assets = service.store.listAssets(summary.home.address);
+    const work = (service.workLedger?.list() ?? []).filter(item => item.requester === summary.home.address && item.returnToSessionId === sessionId
+        || item.assignee === summary.home.address && item.workerSessionId === sessionId)
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
+    const ids = new Set(work.flatMap(item => item.projectId ? [item.projectId] : []));
+    for (const participation of service.ledger.listProjectTurns()) {
+        if (participation.sessionId === sessionId)
+            ids.add(participation.projectId);
+    }
+    const projects = (service.projectLedger?.list() ?? []).filter(project => (project.lead === summary.home.address || project.seats?.some(seat => seat.homeAddress === summary.home.address && seat.status === 'active'))
+        && (ids.has(project.id) || project.createdBySessionId === sessionId || summary.projectId === project.id));
+    return {
+        summary,
+        frames: frames.state.frames.map(frame => ({ address: frame.address,
+            displayName: service.store.hasHome(frame.address) ? service.store.getHome(frame.address).displayName : frame.address, mode: frame.mode,
+            focused: frames.state.focusAddress === frame.address, refreshRequired: frames.staleFrames.includes(frame.address) })),
+        home: { activeAssets: assets.filter(asset => asset.status === 'active').length,
+            candidates: assets.filter(asset => asset.status === 'candidate').length,
+            pendingProposals: service.ledger.listProposals({ toAddress: summary.home.address, status: 'pending' }).length },
+        work: work.slice(0, 20).map(item => ({ id: item.id, goal: item.goal, requester: item.requester,
+            assignee: item.assignee, status: item.status, updatedAt: item.updatedAt,
+            requesterName: service.store.hasHome(item.requester) ? service.store.getHome(item.requester).displayName : item.requester,
+            assigneeName: service.store.hasHome(item.assignee) ? service.store.getHome(item.assignee).displayName : item.assignee,
+            returnToSessionId: item.returnToSessionId,
+            runtime: item.workerSessionId ? runtime(item.workerSessionId) : 'unloaded',
+            ...(item.workerSessionId ? { workerSessionId: item.workerSessionId } : {}),
+            ...(item.projectId ? { projectId: item.projectId } : {}),
+            ...(item.resultSubject ? { resultSubject: item.resultSubject } : {}),
+            ...(item.resultBody ? { resultBody: item.resultBody } : {}),
+            ...(item.resultArtifacts ? { resultArtifacts: item.resultArtifacts } : {}),
+        })),
+        projects: projects.slice(0, 20).map(project => ({ id: project.id, title: project.title,
+            status: project.status, goal: project.goal })),
+        activity: sessionActivity(events).slice(-100), moreWork: work.length > 20,
+    };
+}
+const ACTIONS = {
+    bizagent_memory_remember: 'memory', bizagent_memory_update: 'memory',
+    bizagent_learning_checkpoint: 'learning', bizagent_memory_propose: 'proposal',
+    bizagent_knowledge_propose: 'proposal', bizagent_work_dispatch: 'work',
+    bizagent_work_start: 'work', bizagent_work_accept: 'work', bizagent_work_complete: 'work',
+    bizagent_work_cancel: 'work', bizagent_project_create: 'project', bizagent_project_submit: 'project',
+    bizagent_project_review: 'project', bizagent_frame_open: 'frame', bizagent_learning_launch: 'learning',
+    bizagent_learning_batch_settle: 'learning', bizagent_worklog_record: 'learning',
+};
+/** Project successful durable results only; a tool call alone is never evidence of success. */
+export function sessionActivity(events) {
+    const calls = new Map();
+    const activity = [];
+    for (const event of events) {
+        if (event.type === 'tool/call' && ACTIONS[event.data.name]) {
+            calls.set(String(event.data.callId), { action: event.data.name, kind: ACTIONS[event.data.name], turn: event.data.turn });
+        }
+        if (event.type !== 'tool/result' || event.data.error !== undefined || event.data.message.isError)
+            continue;
+        const call = calls.get(String(event.data.message.toolCallId));
+        if (!call)
+            continue;
+        calls.delete(String(event.data.message.toolCallId));
+        const text = event.data.message.content.filter(block => block.type === 'text').map(block => block.text).join('\n');
+        if (text.length > 256 * 1024)
+            continue;
+        try {
+            const value = JSON.parse(text);
+            if (!value || typeof value !== 'object' || value.error)
+                continue;
+            const entity = [value.asset, value.work, value.project, value.proposal, value.checkpoint]
+                .find(item => item && typeof item === 'object');
+            const title = entity?.title ?? entity?.description ?? entity?.goal ?? entity?.reason;
+            activity.push({ id: `activity-${event.seq}`, seq: event.seq, turn: call.turn, kind: call.kind,
+                action: call.action, title: typeof title === 'string' ? title.slice(0, 300) : '',
+                ...(typeof entity?.status === 'string' ? { status: entity.status } : {}),
+                ...(typeof entity?.id === 'string' ? { entityId: entity.id } : {}) });
+        }
+        catch { /* Foreign or malformed results stay available in DSH's original tool detail. */ }
+    }
+    return activity;
+}
+//# sourceMappingURL=session-surface.js.map

package/lib/shared-knowledge-review-transport.d.ts

@@ -0,0 +1,28 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { BizAgentService } from './service.js';
+import type { SharedKnowledgeProposal } from './shared-knowledge.js';
+export declare const SHARED_KNOWLEDGE_REVIEW_API = "/api/bizagent/shared-knowledge/decision";
+export interface SharedKnowledgeReviewOptions {
+    authenticateHuman(request: IncomingMessage): {
+        userId: string;
+    } | null | Promise<{
+        userId: string;
+    } | null>;
+    authorizeMutation(request: IncomingMessage, principal: {
+        userId: string;
+    }): boolean | Promise<boolean>;
+    /** The host must check line.admin or platform.admin for this exact proposal. */
+    authorizeProposal(request: IncomingMessage, principal: {
+        userId: string;
+    }, proposal: SharedKnowledgeProposal, action: 'accept' | 'reject'): string | null | Promise<string | null>;
+}
+export declare function createSharedKnowledgeReviewHttpHandler(service: BizAgentService, options: SharedKnowledgeReviewOptions): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+/** Mount on the local DSH web server behind the loopback Host / same-origin route guard. */
+export declare function registerSharedKnowledgeReviewRoute(webServer: {
+    register: (route: {
+        kind: 'exact';
+        path: string;
+        handler: (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+    }) => () => void;
+}, service: BizAgentService, options: SharedKnowledgeReviewOptions): () => void;
+//# sourceMappingURL=shared-knowledge-review-transport.d.ts.map

package/lib/shared-knowledge-review-transport.js

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { guardLocalRoute } from './route-guard.js';
+export const SHARED_KNOWLEDGE_REVIEW_API = '/api/bizagent/shared-knowledge/decision';
+const Decision = z.strictObject({
+    proposalId: z.string().min(1).max(200),
+    action: z.enum(['accept', 'reject']),
+    decision: z.string().trim().min(1).max(4000),
+});
+export function createSharedKnowledgeReviewHttpHandler(service, options) {
+    return async (request, response) => {
+        response.setHeader('Cache-Control', 'no-store');
+        response.setHeader('Content-Type', 'application/json; charset=utf-8');
+        response.setHeader('X-Content-Type-Options', 'nosniff');
+        const reply = (code, value) => {
+            response.statusCode = code;
+            response.end(JSON.stringify(value));
+        };
+        if (request.method !== 'GET' && request.method !== 'POST') {
+            response.setHeader('Allow', 'GET, POST');
+            reply(405, { error: 'method-not-allowed' });
+            return;
+        }
+        try {
+            const principal = await options.authenticateHuman(request);
+            if (!principal?.userId.trim()) {
+                reply(401, { error: 'authentication-required' });
+                return;
+            }
+            if (request.method === 'GET') {
+                const proposals = service.ledger.listSharedKnowledgeProposals();
+                const visible = [];
+                for (const proposal of proposals) {
+                    const accept = !!(await options.authorizeProposal(request, principal, proposal, 'accept'))?.trim();
+                    const reject = !!(await options.authorizeProposal(request, principal, proposal, 'reject'))?.trim();
+                    if (accept || reject)
+                        visible.push({ proposal, actions: { accept, reject } });
+                }
+                reply(200, { count: visible.length, proposals: visible });
+                return;
+            }
+            if (!await options.authorizeMutation(request, principal)) {
+                reply(403, { error: 'mutation-forbidden' });
+                return;
+            }
+            if (!String(request.headers['content-type'] ?? '').toLowerCase().startsWith('application/json')) {
+                reply(415, { error: 'content-type' });
+                return;
+            }
+            const parts = [];
+            let bytes = 0;
+            for await (const chunk of request) {
+                const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                bytes += part.length;
+                if (bytes > 16 * 1024) {
+                    reply(413, { error: 'body-too-large' });
+                    return;
+                }
+                parts.push(part);
+            }
+            const input = Decision.parse(JSON.parse(Buffer.concat(parts).toString('utf8')));
+            const proposal = service.ledger.getSharedKnowledgeProposal(input.proposalId);
+            if (!proposal) {
+                reply(404, { error: 'proposal-not-found' });
+                return;
+            }
+            const authorityRef = await options.authorizeProposal(request, principal, proposal, input.action);
+            if (!authorityRef?.trim()) {
+                reply(403, { error: 'proposal-forbidden' });
+                return;
+            }
+            reply(200, await service.decideSharedKnowledgeAsHuman({ ...input,
+                reviewerId: principal.userId, authorityRef }));
+        }
+        catch (error) {
+            reply(error instanceof z.ZodError || error instanceof SyntaxError ? 400 : 409, { error: error instanceof z.ZodError || error instanceof SyntaxError
+                    ? 'invalid-request' : 'shared-knowledge-conflict' });
+        }
+    };
+}
+/** Mount on the local DSH web server behind the loopback Host / same-origin route guard. */
+export function registerSharedKnowledgeReviewRoute(webServer, service, options) {
+    return webServer.register({ kind: 'exact', path: SHARED_KNOWLEDGE_REVIEW_API,
+        handler: guardLocalRoute(createSharedKnowledgeReviewHttpHandler(service, options)) });
+}
+//# sourceMappingURL=shared-knowledge-review-transport.js.map

package/lib/shared-knowledge.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+declare const DocumentSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    scope: z.ZodEnum<{
+        line: "line";
+        common: "common";
+    }>;
+    line: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    proposalId: z.ZodString;
+    reviewerId: z.ZodString;
+    authorityRef: z.ZodString;
+    publishedAt: z.ZodString;
+    bodySha256: z.ZodString;
+}, z.core.$strict>;
+export type SharedKnowledgeTarget = {
+    scope: 'line';
+    line: string;
+} | {
+    scope: 'common';
+};
+export type SharedKnowledgeDocument = z.infer<typeof DocumentSchema> & {
+    body: string;
+    path: string;
+};
+export type PublishSharedKnowledgeInput = SharedKnowledgeTarget & {
+    id: string;
+    description: string;
+    body: string;
+    proposalId: string;
+    reviewerId: string;
+    authorityRef: string;
+    publishedAt: string;
+};
+export declare const SharedKnowledgeProposalSchema: z.ZodObject<{
+    id: z.ZodString;
+    fromAddress: z.ZodString;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        scope: z.ZodLiteral<"line">;
+        line: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        scope: z.ZodLiteral<"common">;
+    }, z.core.$strict>], "scope">;
+    description: z.ZodString;
+    body: z.ZodString;
+    sourceRefs: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"session-events">;
+        sessionId: z.ZodString;
+        fromSeq: z.ZodNumber;
+        toSeq: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"worklog">;
+        sessionId: z.ZodString;
+        revisionId: z.ZodString;
+        fingerprint: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"tool-result">;
+        sessionId: z.ZodString;
+        eventSeq: z.ZodNumber;
+        toolCallId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"artifact">;
+        uri: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"document">;
+        uri: z.ZodString;
+        digest: z.ZodString;
+        authority: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"asset">;
+        ownerAddress: z.ZodString;
+        assetId: z.ZodString;
+        revision: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"user-confirmation">;
+        sessionId: z.ZodString;
+        eventSeq: z.ZodNumber;
+    }, z.core.$strip>], "type">>;
+    status: z.ZodEnum<{
+        rejected: "rejected";
+        pending: "pending";
+        accepted: "accepted";
+    }>;
+    humanReview: z.ZodOptional<z.ZodObject<{
+        reviewerId: z.ZodString;
+        authorityRef: z.ZodString;
+        action: z.ZodEnum<{
+            accept: "accept";
+            reject: "reject";
+        }>;
+        decision: z.ZodString;
+        reviewedAt: z.ZodString;
+    }, z.core.$strict>>;
+    targetDocumentId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    decidedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SharedKnowledgeProposal = z.infer<typeof SharedKnowledgeProposalSchema>;
+/** File-backed shared sources. PMO Agent Home knowledge stays in its separate Home directory. */
+export declare class SharedKnowledgeStore {
+    readonly root: string;
+    constructor(root: string);
+    pathFor(target: SharedKnowledgeTarget): string;
+    publish(input: PublishSharedKnowledgeInput): Promise<SharedKnowledgeDocument>;
+    read(target: SharedKnowledgeTarget, idInput: string): Promise<SharedKnowledgeDocument | undefined>;
+    /**
+     * Search the shared layers. A document that fails its safety or integrity checks is skipped and
+     * reported through `onSkip`, so one hand-edited file cannot break retrieval for every Home.
+     */
+    search(targets: readonly SharedKnowledgeTarget[], query?: string, onSkip?: (path: string, error: unknown) => void): Promise<SharedKnowledgeDocument[]>;
+    private ensureDirectory;
+    private safeExistingDirectory;
+}
+export {};
+//# sourceMappingURL=shared-knowledge.d.ts.map

package/lib/shared-knowledge.js

@@ -0,0 +1,240 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { link, lstat, mkdir, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import YAML from 'yaml';
+import { z } from 'zod';
+import { EvidenceRefSchema, HomeAddressSchema } from './domain.js';
+const LineId = z.string().regex(/^[a-z0-9][a-z0-9._-]{0,127}$/i);
+const KnowledgeId = z.string().regex(/^knowledge-[a-f0-9]{20}$/);
+const DocumentSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    id: KnowledgeId,
+    scope: z.enum(['line', 'common']),
+    line: LineId.optional(),
+    description: z.string().trim().min(1).max(1000),
+    proposalId: z.string().min(1),
+    reviewerId: z.string().trim().min(1),
+    authorityRef: z.string().trim().min(1),
+    publishedAt: z.string().datetime(),
+    bodySha256: z.string().regex(/^[a-f0-9]{64}$/),
+}).superRefine((value, context) => {
+    if ((value.scope === 'line') !== (value.line !== undefined)) {
+        context.addIssue({ code: 'custom', path: ['line'], message: 'line scope requires one line ID' });
+    }
+});
+export const SharedKnowledgeProposalSchema = z.strictObject({
+    id: z.string().regex(/^proposal-[a-f0-9]{20}$/),
+    fromAddress: HomeAddressSchema,
+    target: z.discriminatedUnion('scope', [
+        z.strictObject({ scope: z.literal('line'), line: LineId }),
+        z.strictObject({ scope: z.literal('common') }),
+    ]),
+    description: z.string().trim().min(1).max(1000),
+    body: z.string().trim().min(1).max(128 * 1024),
+    sourceRefs: z.array(EvidenceRefSchema).min(1),
+    status: z.enum(['pending', 'accepted', 'rejected']),
+    humanReview: z.strictObject({
+        reviewerId: z.string().trim().min(1),
+        authorityRef: z.string().trim().min(1),
+        action: z.enum(['accept', 'reject']),
+        decision: z.string().trim().min(1),
+        reviewedAt: z.string().datetime(),
+    }).optional(),
+    targetDocumentId: KnowledgeId.optional(),
+    createdAt: z.string().datetime(),
+    decidedAt: z.string().datetime().optional(),
+}).superRefine((proposal, context) => {
+    if (proposal.status === 'accepted' && (!proposal.targetDocumentId || proposal.humanReview?.action !== 'accept')) {
+        context.addIssue({ code: 'custom', message: 'accepted shared Knowledge needs a reviewed document' });
+    }
+    if (proposal.status === 'rejected' && (proposal.targetDocumentId || proposal.humanReview?.action !== 'reject')) {
+        context.addIssue({ code: 'custom', message: 'rejected shared Knowledge needs a human rejection' });
+    }
+    if (proposal.humanReview && proposal.status === 'pending' && proposal.humanReview.action !== 'accept') {
+        context.addIssue({ code: 'custom', message: 'pending shared Knowledge can only reserve acceptance' });
+    }
+    if (proposal.status !== 'pending' && proposal.decidedAt !== proposal.humanReview?.reviewedAt) {
+        context.addIssue({ code: 'custom', message: 'shared Knowledge decision time must match human review' });
+    }
+});
+/** File-backed shared sources. PMO Agent Home knowledge stays in its separate Home directory. */
+export class SharedKnowledgeStore {
+    root;
+    constructor(root) { this.root = resolve(root); }
+    pathFor(target) {
+        return target.scope === 'common'
+            ? join(this.root, 'knowledge', 'common')
+            : join(this.root, 'lines', LineId.parse(target.line), 'knowledge');
+    }
+    async publish(input) {
+        const id = KnowledgeId.parse(input.id);
+        const body = input.body.trim();
+        if (!body || Buffer.byteLength(body) > 128 * 1024) {
+            throw new Error('shared Knowledge body must contain 1 to 131072 bytes');
+        }
+        const metadata = DocumentSchema.parse({
+            schemaVersion: 1, id, scope: input.scope,
+            ...(input.scope === 'line' ? { line: input.line } : {}),
+            description: input.description, proposalId: input.proposalId,
+            reviewerId: input.reviewerId, authorityRef: input.authorityRef,
+            publishedAt: input.publishedAt,
+            bodySha256: createHash('sha256').update(body).digest('hex'),
+        });
+        const directory = await this.ensureDirectory(input);
+        const path = join(directory, `${id}.md`);
+        const existing = await this.read(input, id);
+        if (existing !== undefined) {
+            if (existing.proposalId !== metadata.proposalId || existing.bodySha256 !== metadata.bodySha256
+                || existing.description !== metadata.description || existing.reviewerId !== metadata.reviewerId
+                || existing.authorityRef !== metadata.authorityRef) {
+                throw new Error(`shared Knowledge document conflicts with existing publication: ${id}`);
+            }
+            return existing;
+        }
+        const content = `---\n${YAML.stringify(metadata, { lineWidth: 0 })}---\n${body}\n`;
+        const temporary = join(directory, `.${id}.${process.pid}.${randomUUID()}.tmp`);
+        await writeFile(temporary, content, { flag: 'wx', mode: 0o600 });
+        try {
+            await link(temporary, path);
+        }
+        catch (error) {
+            if (!isExists(error))
+                throw error;
+            const raced = await this.read(input, id);
+            if (raced?.proposalId !== metadata.proposalId || raced.bodySha256 !== metadata.bodySha256) {
+                throw new Error(`shared Knowledge document conflicts with existing publication: ${id}`);
+            }
+            return raced;
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+        return { ...metadata, body, path };
+    }
+    async read(target, idInput) {
+        const id = KnowledgeId.parse(idInput);
+        if (!await this.safeExistingDirectory(target))
+            return undefined;
+        const path = join(this.pathFor(target), `${id}.md`);
+        let info;
+        try {
+            info = await lstat(path);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return undefined;
+            throw error;
+        }
+        if (!info.isFile() || info.isSymbolicLink() || info.size > 160 * 1024) {
+            throw new Error(`unsafe shared Knowledge document: ${path}`);
+        }
+        const content = await readFile(path, 'utf8');
+        const end = content.indexOf('\n---\n', 4);
+        if (!content.startsWith('---\n') || end < 0)
+            throw new Error(`malformed shared Knowledge document: ${path}`);
+        const metadata = DocumentSchema.parse(YAML.parse(content.slice(4, end)));
+        const body = content.slice(end + 5).trim();
+        if (metadata.id !== id || metadata.scope !== target.scope
+            || (target.scope === 'line' && metadata.line !== LineId.parse(target.line))
+            || createHash('sha256').update(body).digest('hex') !== metadata.bodySha256) {
+            throw new Error(`shared Knowledge document integrity mismatch: ${path}`);
+        }
+        return { ...metadata, body, path };
+    }
+    /**
+     * Search the shared layers. A document that fails its safety or integrity checks is skipped and
+     * reported through `onSkip`, so one hand-edited file cannot break retrieval for every Home.
+     */
+    async search(targets, query = '', onSkip) {
+        const terms = query.trim().toLowerCase();
+        const results = [];
+        for (const target of targets) {
+            if (!await this.safeExistingDirectory(target))
+                continue;
+            const directory = this.pathFor(target);
+            let entries;
+            try {
+                entries = await readdir(directory, { withFileTypes: true });
+            }
+            catch (error) {
+                if (isMissing(error))
+                    continue;
+                throw error;
+            }
+            for (const entry of entries) {
+                if (!entry.isFile() || !/^knowledge-[a-f0-9]{20}\.md$/.test(entry.name))
+                    continue;
+                let document;
+                try {
+                    document = await this.read(target, entry.name.slice(0, -3));
+                }
+                catch (error) {
+                    onSkip?.(join(directory, entry.name), error);
+                    continue;
+                }
+                if (document && (!terms || `${document.description}\n${document.body}`.toLowerCase().includes(terms))) {
+                    results.push(document);
+                }
+            }
+        }
+        return results.sort((a, b) => b.publishedAt.localeCompare(a.publishedAt) || a.id.localeCompare(b.id));
+    }
+    async ensureDirectory(target) {
+        if (!isAbsolute(this.root) || await realpath(this.root) !== this.root) {
+            throw new Error('shared Knowledge root must be a real absolute directory');
+        }
+        const segments = target.scope === 'common'
+            ? ['knowledge', 'common'] : ['lines', LineId.parse(target.line), 'knowledge'];
+        let current = this.root;
+        for (const segment of segments) {
+            current = join(current, segment);
+            try {
+                await mkdir(current);
+            }
+            catch (error) {
+                if (!isExists(error))
+                    throw error;
+            }
+            const info = await lstat(current);
+            if (!info.isDirectory() || info.isSymbolicLink()) {
+                throw new Error(`shared Knowledge path must be a real directory: ${current}`);
+            }
+            const canonical = await realpath(current);
+            const rel = relative(this.root, canonical);
+            if (rel.startsWith('..') || isAbsolute(rel))
+                throw new Error('shared Knowledge path escapes its root');
+        }
+        return current;
+    }
+    async safeExistingDirectory(target) {
+        if (await realpath(this.root) !== this.root) {
+            throw new Error('shared Knowledge root must be a real directory');
+        }
+        const segments = target.scope === 'common'
+            ? ['knowledge', 'common'] : ['lines', LineId.parse(target.line), 'knowledge'];
+        let current = this.root;
+        for (const segment of segments) {
+            current = join(current, segment);
+            let info;
+            try {
+                info = await lstat(current);
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return false;
+                throw error;
+            }
+            if (!info.isDirectory() || info.isSymbolicLink()) {
+                throw new Error(`shared Knowledge path must be a real directory: ${current}`);
+            }
+        }
+        return true;
+    }
+}
+function isMissing(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+function isExists(error) {
+    return error instanceof Error && 'code' in error && error.code === 'EEXIST';
+}
+//# sourceMappingURL=shared-knowledge.js.map

package/lib/tools.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { BizAgentService } from './service.js';
+import type { InboxMessage } from './domain.js';
+import type { WorkRunner } from './work-runner.js';
+import type { LearningSessionRunner } from './learning-session-runner.js';
+export declare function registerTools(ctx: Context, service: BizAgentService, workRunner: WorkRunner, learningRunner: LearningSessionRunner, onInboxSent?: (message: InboxMessage) => void): void;
+//# sourceMappingURL=tools.d.ts.map