@krantho/api 0.0.0-stage → 1.0.1

package/dist/assistant/tools/action-tools.js.map

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

package/dist/assistant/tools/aeo-tools.d.ts

@@ -0,0 +1,4 @@
+import { type AssistantTool } from './define-tool.js';
+/** Answer-engine tools */
+export declare const AEO_TOOLS: readonly AssistantTool[];
+//# sourceMappingURL=aeo-tools.d.ts.map

package/dist/assistant/tools/aeo-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aeo-tools.d.ts","sourceRoot":"","sources":["../../../src/assistant/tools/aeo-tools.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,aAAa,EAAgC,MAAM,kBAAkB,CAAA;AAqMnF,0BAA0B;AAC1B,eAAO,MAAM,SAAS,EAAE,SAAS,aAAa,EAI7C,CAAA"}

package/dist/assistant/tools/aeo-tools.js

@@ -0,0 +1,162 @@
+import { canReadPublished } from '@krantho/persistence';
+import { z } from 'zod';
+import { buildLlmsTxt, loadLlmsTxtSnapshot } from '../../handlers/seo-llms-txt.js';
+import { getMergedSchema } from '../../merged-schema.js';
+import { sha256Hex } from '../pending-action.js';
+import { defineTool } from './define-tool.js';
+import { canWriteDrafts } from './draft-tools.js';
+import { prepareDraft, proposeDrafts, writeDraft } from './draft-write.js';
+import { declaresString, faqFit } from './faq-fit.js';
+import { exactDocument, failure, localeOf, pathOf, proposal } from './support.js';
+/** Fields that hold an answer-ready summary, in order of preference */
+const SUMMARY_FIELDS = ['answer-summary', 'tldr', 'summary'];
+/** Output the user can use by hand when nothing can be written */
+function proposedByHand(reason, title, items) {
+    return {
+        result: { ok: true, proposed: true, reason },
+        activity: { status: 'proposed', summary: title, documents: [], proposal: { title, items } },
+    };
+}
+const answerSummaryTool = defineTool({
+    name: 'answer_summary',
+    label: 'Write an answer summary',
+    description: "Save an answer-ready summary of a document: 40 to 60 words that stand alone, state facts, and answer the page's main question. Write the summary yourself from the document you read.",
+    input: z.object({
+        collection: z.string().min(1),
+        slug: z.string().min(1),
+        locale: z.string().min(1).optional(),
+        basedOnVersion: z.int().positive(),
+        summary: z.string().min(20).max(700),
+    }),
+    role: 'editor',
+    available: canWriteDrafts,
+    describe: (input) => `Writing an answer summary for ${pathOf(input)}`,
+    async run(input, run) {
+        const locale = localeOf(run.ctx, input.locale);
+        const path = pathOf(input);
+        const current = await exactDocument(run.ctx, input.collection, input.slug, locale);
+        if (!current)
+            return failure(`${path} does not exist in locale ${locale}`);
+        if (current.meta.version !== input.basedOnVersion) {
+            return failure(`${path} is at v${current.meta.version}, not v${input.basedOnVersion}; read it again`);
+        }
+        const collectionDef = run.ctx.contentConfig.collections.get(input.collection);
+        const schema = collectionDef ? await getMergedSchema(collectionDef, run.ctx.adapter) : null;
+        const field = SUMMARY_FIELDS.find((name) => schema && declaresString(schema, name));
+        if (!field) {
+            return proposedByHand(`The ${input.collection} collection has no answer-summary field, so the summary is shown to the user to use by hand. An admin can add an answer-summary field in the schema editor.`, `Answer summary for ${path}`, [{ label: 'Summary', text: input.summary }]);
+        }
+        const outcome = await writeDraft(run, {
+            ref: { collection: input.collection, slug: input.slug, locale },
+            current,
+            fields: { ...current.fields, [field]: input.summary },
+            body: current.body,
+        });
+        if (outcome.result['ok'] !== true || outcome.result['pending'])
+            return outcome;
+        return { ...outcome, result: { ...outcome.result, field } };
+    },
+});
+/** Validate every candidate as a new draft; the first failure stops the batch */
+async function prepareFaqDrafts(run, collection, locale, candidates) {
+    const drafts = [];
+    for (const candidate of candidates) {
+        const prepared = await prepareDraft(run, {
+            ref: { collection, slug: candidate.slug, locale },
+            current: null,
+            fields: candidate.fields,
+            body: candidate.body,
+        });
+        if (!prepared.ok)
+            return prepared;
+        drafts.push(prepared.draft);
+    }
+    return { ok: true, drafts };
+}
+function entryItems(entries) {
+    return entries.map((entry) => ({ label: entry.question, text: entry.answer }));
+}
+const faqFromDocumentTool = defineTool({
+    name: 'faq_from_document',
+    label: 'Create FAQ entries',
+    description: 'Turn questions and answers you wrote from a document into FAQ entries, one draft document per entry in the collection the user chose. Ask the user which collection when they have not said. Always proposed to the user.',
+    input: z.object({
+        sourceCollection: z.string().min(1),
+        sourceSlug: z.string().min(1),
+        targetCollection: z.string().min(1),
+        locale: z.string().min(1).optional(),
+        entries: z
+            .array(z.object({ question: z.string().min(1).max(300), answer: z.string().min(1).max(2000) }))
+            .min(1)
+            .max(20),
+    }),
+    role: 'editor',
+    available: canWriteDrafts,
+    describe: (input) => `Preparing FAQ entries in ${input.targetCollection}`,
+    async run(input, run) {
+        const locale = localeOf(run.ctx, input.locale);
+        const source = { collection: input.sourceCollection, slug: input.sourceSlug };
+        if (!(await exactDocument(run.ctx, source.collection, source.slug, locale))) {
+            return failure(`${pathOf(source)} does not exist in locale ${locale}`);
+        }
+        const fit = await faqFit(run.ctx, input.targetCollection, input.entries, locale);
+        const title = `FAQ entries from ${pathOf(source)}`;
+        if (!fit.ok) {
+            return proposedByHand(`${fit.reason}. The entries are shown to the user.`, title, entryItems(input.entries));
+        }
+        const prepared = await prepareFaqDrafts(run, input.targetCollection, locale, fit.candidates);
+        if (!prepared.ok)
+            return prepared.outcome;
+        const count = prepared.drafts.length;
+        return proposeDrafts(run, prepared.drafts, `Create ${count} FAQ ${count === 1 ? 'entry' : 'entries'} in ${input.targetCollection}`, `Proposed ${count} FAQ ${count === 1 ? 'entry' : 'entries'} — needs your confirmation`);
+    },
+});
+const regenerateLlmsTxtTool = defineTool({
+    name: 'regenerate_llms_txt',
+    label: 'Regenerate llms.txt',
+    description: "Regenerate the site's llms.txt from its live pages, optionally with a site summary and link descriptions you wrote. Proposed to the user with the current and the new text.",
+    input: z.object({
+        summary: z.string().min(1).max(500).optional(),
+        descriptions: z
+            .array(z.object({
+            collection: z.string().min(1),
+            slug: z.string().min(1),
+            description: z.string().min(1).max(300),
+        }))
+            .max(200)
+            .optional(),
+    }),
+    role: 'admin',
+    available: (ctx) => ctx.siteSettingsAdapter !== undefined && canReadPublished(ctx.adapter),
+    describe: () => 'Regenerating llms.txt',
+    async run(input, run) {
+        const descriptions = new Map((input.descriptions ?? []).map((d) => [`${d.collection}/${d.slug}`, d.description]));
+        const text = await buildLlmsTxt(run.ctx, { summary: input.summary, descriptions });
+        const snapshot = await loadLlmsTxtSnapshot(run.ctx);
+        const served = snapshot ?? (await buildLlmsTxt(run.ctx));
+        if (text === served) {
+            return {
+                result: { ok: true, unchanged: true },
+                activity: { status: 'done', summary: 'llms.txt is unchanged', documents: [] },
+            };
+        }
+        return proposal(run, { kind: 'save_llms_txt', beforeHash: sha256Hex(snapshot ?? ''), text }, { title: 'Save the new llms.txt', confirmLabel: 'Save llms.txt', destructive: false }, {
+            summary: 'Proposed a new llms.txt — needs your confirmation',
+            documents: [],
+            proposal: {
+                title: 'llms.txt',
+                items: [
+                    { label: 'Current', text: served },
+                    { label: 'Proposed', text },
+                ],
+            },
+        });
+    },
+});
+/** Answer-engine tools */
+export const AEO_TOOLS = [
+    answerSummaryTool,
+    faqFromDocumentTool,
+    regenerateLlmsTxtTool,
+];
+//# sourceMappingURL=aeo-tools.js.map

package/dist/assistant/tools/aeo-tools.js.map

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

package/dist/assistant/tools/define-tool.d.ts

@@ -0,0 +1,55 @@
+import type { Role } from '@krantho/persistence';
+import type { ZodObject, ZodRawShape, z } from 'zod';
+import type { ApiContext } from '../../types.js';
+import type { AssistantActivity } from '../protocol.js';
+import type { WritePolicy } from '../write-policy.js';
+/** What a tool runs with: the request's authenticated context and its write policy */
+export interface ToolRunContext {
+    /** The request's context, with the signed-in user in `auth` */
+    ctx: ApiContext;
+    callId: string;
+    writes: WritePolicy;
+    /** Frames document text for the model with this request's nonce */
+    frame: (source: string, text: string) => string;
+    signal: AbortSignal;
+    /** Counts a model call a tool makes itself toward the request's token budget */
+    spend: (usage: {
+        inputTokens: number;
+        outputTokens: number;
+    }) => void;
+}
+/** A tool's result for the model and the activity Studio shows */
+export interface ToolOutcome {
+    result: Record<string, unknown>;
+    activity: Omit<AssistantActivity, 'id' | 'tool'>;
+}
+/** A server-side tool the model may call */
+export interface AssistantTool {
+    name: string;
+    /** A short human name, e.g. "Read documents" */
+    label: string;
+    /** Shown in Studio before the result arrives */
+    describe(input: Record<string, unknown>): string;
+    description: string;
+    input: ZodObject<ZodRawShape>;
+    /** The role the matching REST handler requires */
+    role: Role;
+    /** Whether this deployment can run it */
+    available(ctx: ApiContext): boolean;
+    /** Runs with input the `input` schema has validated */
+    run(input: Record<string, unknown>, run: ToolRunContext): Promise<ToolOutcome>;
+}
+/** A tool definition whose `describe` and `run` see the parsed input's type */
+export interface ToolSpec<S extends ZodRawShape> {
+    name: string;
+    label: string;
+    description: string;
+    input: ZodObject<S>;
+    role: Role;
+    available(ctx: ApiContext): boolean;
+    describe(input: z.infer<ZodObject<S>>): string;
+    run(input: z.infer<ZodObject<S>>, run: ToolRunContext): Promise<ToolOutcome>;
+}
+/** Declare a tool; the loop validates every call with `input` before `run` sees it */
+export declare function defineTool<S extends ZodRawShape>(spec: ToolSpec<S>): AssistantTool;
+//# sourceMappingURL=define-tool.d.ts.map

package/dist/assistant/tools/define-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../../../src/assistant/tools/define-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,GAAG,EAAE,UAAU,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,WAAW,CAAA;IACnB,mEAAmE;IACnE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IAC/C,MAAM,EAAE,WAAW,CAAA;IACnB,gFAAgF;IAChF,KAAK,EAAE,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACtE;AAED,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,MAAM,CAAC,CAAA;CACjD;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;IAChD,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,CAAC,WAAW,CAAC,CAAA;IAC7B,kDAAkD;IAClD,IAAI,EAAE,IAAI,CAAA;IACV,yCAAyC;IACzC,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAA;IACnC,uDAAuD;IACvD,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CAC/E;AAED,+EAA+E;AAC/E,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,WAAW;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACnB,IAAI,EAAE,IAAI,CAAA;IACV,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAA;IACnC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAA;IAC9C,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CAC7E;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,aAAa,CAElF"}

package/dist/assistant/tools/define-tool.js

@@ -0,0 +1,5 @@
+/** Declare a tool; the loop validates every call with `input` before `run` sees it */
+export function defineTool(spec) {
+    return spec;
+}
+//# sourceMappingURL=define-tool.js.map

package/dist/assistant/tools/define-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.js","sourceRoot":"","sources":["../../../src/assistant/tools/define-tool.ts"],"names":[],"mappings":"AAsDA,sFAAsF;AACtF,MAAM,UAAU,UAAU,CAAwB,IAAiB;IACjE,OAAO,IAAgC,CAAA;AACzC,CAAC"}

package/dist/assistant/tools/draft-tools.d.ts

@@ -0,0 +1,7 @@
+import type { ApiContext } from '../../types.js';
+import { type AssistantTool } from './define-tool.js';
+/** Draft writes land in version history, so they need a versioned adapter that can write and read */
+export declare function canWriteDrafts(ctx: ApiContext): boolean;
+/** Tools that write drafts */
+export declare const DRAFT_TOOLS: readonly AssistantTool[];
+//# sourceMappingURL=draft-tools.d.ts.map

package/dist/assistant/tools/draft-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-tools.d.ts","sourceRoot":"","sources":["../../../src/assistant/tools/draft-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD,OAAO,EAAE,KAAK,aAAa,EAAc,MAAM,kBAAkB,CAAA;AAKjE,qGAAqG;AACrG,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEvD;AA2GD,8BAA8B;AAC9B,eAAO,MAAM,WAAW,EAAE,SAAS,aAAa,EAAuC,CAAA"}

package/dist/assistant/tools/draft-tools.js

@@ -0,0 +1,105 @@
+import { canGetContent, canWriteContent, hasVersioning } from '@krantho/persistence';
+import { z } from 'zod';
+import { replaceSections } from '../document-change.js';
+import { defineTool } from './define-tool.js';
+import { writeDraft } from './draft-write.js';
+import { documentView } from './read-tools.js';
+import { exactDocument, failure, localeOf, pathOf } from './support.js';
+/** Draft writes land in version history, so they need a versioned adapter that can write and read */
+export function canWriteDrafts(ctx) {
+    return canWriteContent(ctx.adapter) && hasVersioning(ctx.adapter) && canGetContent(ctx.adapter);
+}
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const createDraftTool = defineTool({
+    name: 'create_draft',
+    label: 'Create a draft',
+    description: 'Create a new document as a draft. Use get_schema first so the fields are valid. The slug is kebab-case.',
+    input: z.object({
+        collection: z.string().min(1),
+        slug: z.string().min(1).max(80).regex(SLUG).describe('kebab-case, for example opening-hours'),
+        fields: z.record(z.string(), z.unknown()).describe('Field values keyed by field name'),
+        body: z.string().optional().describe('Markdown body'),
+        locale: z.string().min(1).optional(),
+    }),
+    role: 'editor',
+    available: canWriteDrafts,
+    describe: (input) => `Creating draft ${pathOf(input)}`,
+    async run(input, run) {
+        const locale = localeOf(run.ctx, input.locale);
+        const existing = await exactDocument(run.ctx, input.collection, input.slug, locale);
+        if (existing) {
+            return failure(`${pathOf(input)} already exists (v${existing.meta.version}); read it and use update_draft`);
+        }
+        return writeDraft(run, {
+            ref: { collection: input.collection, slug: input.slug, locale },
+            current: null,
+            fields: input.fields,
+            body: input.body ?? '',
+        });
+    },
+});
+/** The current fields with the given values merged in; `null` removes a key */
+function mergeFields(current, changes) {
+    const merged = { ...current };
+    for (const [key, value] of Object.entries(changes ?? {})) {
+        if (value === null)
+            delete merged[key];
+        else
+            merged[key] = value;
+    }
+    return merged;
+}
+const updateDraftTool = defineTool({
+    name: 'update_draft',
+    label: 'Update a draft',
+    description: 'Change an existing document and save it as a draft. Pass the version you read with get_document as basedOnVersion. Change fields, replace the whole body, or replace the content under chosen ## section headings (body and sections exclusive). Filling empty fields is saved at once; replacing text is proposed to the user with the difference.',
+    input: z.object({
+        collection: z.string().min(1),
+        slug: z.string().min(1),
+        locale: z.string().min(1).optional(),
+        basedOnVersion: z.int().positive(),
+        fields: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('Field values to set; null removes a field'),
+        body: z.string().optional().describe('The whole new markdown body'),
+        sections: z
+            .array(z.object({ heading: z.string().min(1), content: z.string() }))
+            .min(1)
+            .optional()
+            .describe('New content under existing ## headings'),
+    }),
+    role: 'editor',
+    available: canWriteDrafts,
+    describe: (input) => `Updating ${pathOf(input)}`,
+    async run(input, run) {
+        if (input.body !== undefined && input.sections) {
+            return failure('Pass either body or sections, not both');
+        }
+        if (!input.fields && input.body === undefined && !input.sections) {
+            return failure('Nothing to change: pass fields, body or sections');
+        }
+        const locale = localeOf(run.ctx, input.locale);
+        const current = await exactDocument(run.ctx, input.collection, input.slug, locale);
+        if (!current)
+            return failure(`${pathOf(input)} does not exist in locale ${locale}`);
+        if (current.meta.version !== input.basedOnVersion) {
+            return failure(`${pathOf(input)} is at v${current.meta.version}, not v${input.basedOnVersion}; read it again`);
+        }
+        if (input.body !== undefined && documentView(run, current).bodyTruncated) {
+            return failure(`The body of ${pathOf(input)} is longer than you could read; change it with sections instead`);
+        }
+        const body = input.sections
+            ? replaceSections(current.body, input.sections)
+            : (input.body ?? current.body);
+        return writeDraft(run, {
+            ref: { collection: input.collection, slug: input.slug, locale },
+            current,
+            fields: mergeFields(current.fields, input.fields),
+            body,
+        });
+    },
+});
+/** Tools that write drafts */
+export const DRAFT_TOOLS = [createDraftTool, updateDraftTool];
+//# sourceMappingURL=draft-tools.js.map

package/dist/assistant/tools/draft-tools.js.map

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

package/dist/assistant/tools/draft-write.d.ts

@@ -0,0 +1,49 @@
+import type { ContentDocument } from '@krantho/persistence';
+import { type BaseState } from '../pending-action.js';
+import type { DocumentChange } from '../protocol.js';
+import type { ToolOutcome, ToolRunContext } from './define-tool.js';
+/** One document's proposed after-state */
+export interface DraftWrite {
+    ref: {
+        collection: string;
+        slug: string;
+        locale: string;
+    };
+    /** The current version, or null for a new document */
+    current: ContentDocument | null;
+    fields: Record<string, unknown>;
+    body: string;
+}
+/** A draft ready to write or propose: the validated after-state and what it changes */
+export interface PreparedDraft {
+    write: DraftWrite;
+    fields: Record<string, unknown>;
+    change: DocumentChange;
+}
+/** A save's base state: the version and hash of the current document */
+export declare function baseStateOf(write: DraftWrite): BaseState;
+/**
+ * Validate a draft's after-state against the active contract (the values a save
+ * would write; a save keeps the document's publication state) and diff it
+ * against the current version.
+ * Fails when the collection is unknown, the fields do not validate, or nothing
+ * changes.
+ */
+export declare function prepareDraft(run: ToolRunContext, write: DraftWrite): Promise<{
+    ok: true;
+    draft: PreparedDraft;
+} | {
+    ok: false;
+    outcome: ToolOutcome;
+}>;
+/** A lock someone else holds on the document, as a failed outcome */
+export declare function lockedOutcome(run: ToolRunContext, ref: DraftWrite['ref']): Promise<ToolOutcome | null>;
+/** Propose saving drafts of several documents: nothing is written until the user confirms */
+export declare function proposeDrafts(run: ToolRunContext, drafts: readonly PreparedDraft[], title: string, summary: string): ToolOutcome;
+/**
+ * Save one document's draft through the write policy: written at once when it
+ * creates the document or only fills empty values (and no other document was
+ * written in this request), otherwise proposed with its diff.
+ */
+export declare function writeDraft(run: ToolRunContext, write: DraftWrite): Promise<ToolOutcome>;
+//# sourceMappingURL=draft-write.d.ts.map

package/dist/assistant/tools/draft-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-write.d.ts","sourceRoot":"","sources":["../../../src/assistant/tools/draft-write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAO3D,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,sBAAsB,CAAA;AAChE,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,gBAAgB,CAAA;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGnE,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACzD,sDAAsD;IACtD,OAAO,EAAE,eAAe,GAAG,IAAI,CAAA;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,IAAI,EAAE,MAAM,CAAA;CACb;AAED,uFAAuF;AACvF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAA;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,MAAM,EAAE,cAAc,CAAA;CACvB;AAWD,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAMxD;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC,CA0BnF;AAED,qEAAqE;AACrE,wBAAsB,aAAa,CACjC,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,GACrB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAK7B;AAgCD,6FAA6F;AAC7F,wBAAgB,aAAa,CAC3B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,WAAW,CAgBb;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAY7F"}

package/dist/assistant/tools/draft-write.js

@@ -0,0 +1,122 @@
+import { lockHolder } from '../../content-locks.js';
+import { prepareFields, saveDocument } from '../../save-document.js';
+import { responseError } from '../call-handler.js';
+import { diffDocument } from '../document-change.js';
+import { lockMessage } from '../document-lock.js';
+import { stateHash } from '../pending-action.js';
+import { assistantChangedBy, exactDocument, failure, pathOf, proposal } from './support.js';
+/** The failure a response carries, with any validation details spelled out */
+function responseFailure(response, documents) {
+    const details = response.body
+        ?.details;
+    const detail = details?.map((d) => `${d.field}: ${d.message}`).join('; ');
+    const error = detail ? `${responseError(response)} — ${detail}` : responseError(response);
+    return failure(error, { documents });
+}
+/** A save's base state: the version and hash of the current document */
+export function baseStateOf(write) {
+    return {
+        ...write.ref,
+        baseVersion: write.current?.meta.version ?? 0,
+        baseHash: stateHash(write.current),
+    };
+}
+/**
+ * Validate a draft's after-state against the active contract (the values a save
+ * would write; a save keeps the document's publication state) and diff it
+ * against the current version.
+ * Fails when the collection is unknown, the fields do not validate, or nothing
+ * changes.
+ */
+export async function prepareDraft(run, write) {
+    const collectionDef = run.ctx.contentConfig.collections.get(write.ref.collection);
+    if (!collectionDef) {
+        return { ok: false, outcome: failure(`Collection "${write.ref.collection}" not found`) };
+    }
+    const prepared = await prepareFields(run.ctx, collectionDef, {
+        fields: write.fields,
+        body: write.body,
+        metadata: write.current?.metadata ?? {},
+    });
+    if (!prepared.ok)
+        return { ok: false, outcome: responseFailure(prepared.response, []) };
+    const baseVersion = write.current?.meta.version ?? 0;
+    const change = diffDocument({ ...write.ref, version: baseVersion || undefined }, baseVersion, write.current, {
+        fields: prepared.fields,
+        body: write.body,
+    });
+    if (write.current && change.fields.length === 0 && !change.body) {
+        return { ok: false, outcome: failure(`Nothing to change in ${pathOf(write.ref)}`) };
+    }
+    return { ok: true, draft: { write, fields: prepared.fields, change } };
+}
+/** A lock someone else holds on the document, as a failed outcome */
+export async function lockedOutcome(run, ref) {
+    const lock = await lockHolder(run.ctx, ref);
+    if (!lock)
+        return null;
+    const message = lockMessage(ref, lock);
+    return failure(message, { summary: message, documents: [ref] });
+}
+/** Write a prepared draft now, as a new version recorded as made through the assistant; what visitors see is unchanged */
+async function commitDraft(run, draft) {
+    const { write, change } = draft;
+    const isNew = write.current === null;
+    const saved = await saveDocument(run.ctx, {
+        ...write.ref,
+        fields: draft.fields,
+        body: write.body,
+        isNew,
+        expectedVersion: write.current?.meta.version,
+        changedBy: assistantChangedBy(run.ctx.auth),
+    });
+    if (!saved.ok)
+        return responseFailure(saved.response, [write.ref]);
+    const after = await exactDocument(run.ctx, write.ref.collection, write.ref.slug, write.ref.locale);
+    const ref = { ...write.ref, version: after?.meta.version };
+    run.writes.recordWrite(change);
+    const changed = [...change.fields.map((field) => field.name), ...(change.body ? ['body'] : [])];
+    const verb = isNew ? 'Created' : 'Updated';
+    return {
+        result: { ok: true, ref, version: ref.version, changed },
+        activity: {
+            status: 'done',
+            summary: `${verb} draft ${pathOf(ref)} (v${ref.version ?? '?'})`,
+            documents: [ref],
+            changes: [change],
+        },
+    };
+}
+/** Propose saving drafts of several documents: nothing is written until the user confirms */
+export function proposeDrafts(run, drafts, title, summary) {
+    const documents = drafts.map((draft) => ({
+        ...baseStateOf(draft.write),
+        fields: draft.fields,
+        body: draft.write.body,
+    }));
+    return proposal(run, { kind: 'save_documents', documents }, { title, confirmLabel: drafts.length > 1 ? 'Save drafts' : 'Save draft', destructive: false }, {
+        summary,
+        documents: drafts.map((draft) => draft.change.ref),
+        changes: drafts.map((draft) => draft.change),
+    });
+}
+/**
+ * Save one document's draft through the write policy: written at once when it
+ * creates the document or only fills empty values (and no other document was
+ * written in this request), otherwise proposed with its diff.
+ */
+export async function writeDraft(run, write) {
+    const locked = await lockedOutcome(run, write.ref);
+    if (locked)
+        return locked;
+    const prepared = await prepareDraft(run, write);
+    if (!prepared.ok)
+        return prepared.outcome;
+    const { draft } = prepared;
+    if (run.writes.decide(draft.change) === 'write')
+        return commitDraft(run, draft);
+    const path = pathOf(write.ref);
+    const title = write.current ? `Save a draft of ${path}` : `Create draft ${path}`;
+    return proposeDrafts(run, [draft], title, `Proposed changes to ${path} — needs your confirmation`);
+}
+//# sourceMappingURL=draft-write.js.map

package/dist/assistant/tools/draft-write.js.map

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

package/dist/assistant/tools/faq-fit.d.ts

@@ -0,0 +1,32 @@
+import { type ZodObject, type ZodRawShape } from 'zod';
+import type { ApiContext } from '../../types.js';
+/** One question and its answer */
+export interface FaqEntry {
+    question: string;
+    answer: string;
+}
+/** A new document one FAQ entry becomes */
+export interface FaqCandidate {
+    slug: string;
+    fields: Record<string, unknown>;
+    body: string;
+}
+export type FaqFit = {
+    ok: true;
+    candidates: FaqCandidate[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Whether the schema declares `key` as a string field */
+export declare function declaresString(schema: ZodObject<ZodRawShape>, key: string): boolean;
+/** The question as a slug: lowercased, accents removed, runs of other characters as `-` */
+export declare function questionSlug(question: string): string;
+/**
+ * Whether FAQ entries fit a collection: it must declare `question` as a string,
+ * and each entry's fields must pass its schema. The answer goes to an `answer`
+ * field when declared, else to the body; `title` is the question. Each entry
+ * gets a slug unique in the collection and in the batch.
+ */
+export declare function faqFit(ctx: ApiContext, collection: string, entries: readonly FaqEntry[], locale: string): Promise<FaqFit>;
+//# sourceMappingURL=faq-fit.d.ts.map

package/dist/assistant/tools/faq-fit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faq-fit.d.ts","sourceRoot":"","sources":["../../../src/assistant/tools/faq-fit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAK,MAAM,KAAK,CAAA;AAEzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD,kCAAkC;AAClC,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,MAAM,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,YAAY,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7F,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQnF;AAID,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUrD;AAoCD;;;;;GAKG;AACH,wBAAsB,MAAM,CAC1B,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CA2BjB"}