@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/dist/walkthroughs.d.ts

@@ -0,0 +1,224 @@
+import { z } from 'zod';
+import type { Bridge } from './bridge.js';
+import { contextSchema } from './schema.js';
+export declare const walkthroughSchema: z.ZodObject<{
+    id: z.ZodString;
+    project_id: z.ZodString;
+    article_id: z.ZodString;
+    title: z.ZodString;
+    slug: z.ZodString;
+    revision: z.ZodString;
+    generation_status: z.ZodEnum<{
+        running: "running";
+        failed: "failed";
+        pending: "pending";
+        completed: "completed";
+    }>;
+    ready: z.ZodBoolean;
+    narrated: z.ZodBoolean;
+    publication_pending: z.ZodBoolean;
+    shared: z.ZodBoolean;
+    public_on_article: z.ZodBoolean;
+    review_url: z.ZodURL;
+    playback_url: z.ZodNullable<z.ZodURL>;
+    public_url: z.ZodNullable<z.ZodURL>;
+    article_public_url: z.ZodNullable<z.ZodURL>;
+    assets: z.ZodObject<{
+        video: z.ZodBoolean;
+        narrated_video: z.ZodBoolean;
+        subtitles: z.ZodBoolean;
+        transcript: z.ZodBoolean;
+        poster: z.ZodBoolean;
+    }, z.core.$strip>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    generated_at: z.ZodNullable<z.ZodISODateTime>;
+    shared_at: z.ZodNullable<z.ZodISODateTime>;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+    transcript_text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    transcript_omitted: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type Context = z.infer<typeof contextSchema>;
+export declare class Walkthroughs {
+    private bridge;
+    constructor(bridge: Bridge);
+    private supported;
+    private check;
+    list(input?: {
+        after_id?: string;
+        through_id?: string;
+        article_id?: string;
+    }, context?: Context): Promise<{
+        project_id: string;
+        through_id: string;
+        next_cursor: string | null;
+        walkthroughs: {
+            id: string;
+            project_id: string;
+            article_id: string;
+            title: string;
+            slug: string;
+            revision: string;
+            generation_status: "running" | "failed" | "pending" | "completed";
+            ready: boolean;
+            narrated: boolean;
+            publication_pending: boolean;
+            shared: boolean;
+            public_on_article: boolean;
+            review_url: string;
+            playback_url: string | null;
+            public_url: string | null;
+            article_public_url: string | null;
+            assets: {
+                video: boolean;
+                narrated_video: boolean;
+                subtitles: boolean;
+                transcript: boolean;
+                poster: boolean;
+            };
+            created_at: string;
+            updated_at: string;
+            generated_at: string | null;
+            shared_at: string | null;
+            error: {
+                code: string;
+                message: string;
+            } | null;
+            transcript_text?: string | null | undefined;
+            transcript_omitted?: boolean | undefined;
+        }[];
+    }>;
+    get(id: string): Promise<{
+        id: string;
+        project_id: string;
+        article_id: string;
+        title: string;
+        slug: string;
+        revision: string;
+        generation_status: "running" | "failed" | "pending" | "completed";
+        ready: boolean;
+        narrated: boolean;
+        publication_pending: boolean;
+        shared: boolean;
+        public_on_article: boolean;
+        review_url: string;
+        playback_url: string | null;
+        public_url: string | null;
+        article_public_url: string | null;
+        assets: {
+            video: boolean;
+            narrated_video: boolean;
+            subtitles: boolean;
+            transcript: boolean;
+            poster: boolean;
+        };
+        created_at: string;
+        updated_at: string;
+        generated_at: string | null;
+        shared_at: string | null;
+        error: {
+            code: string;
+            message: string;
+        } | null;
+        transcript_text?: string | null | undefined;
+        transcript_omitted?: boolean | undefined;
+    }>;
+    refresh(context: Context, previous?: unknown): Promise<{
+        status: "unsupported";
+        instructions: string;
+        synced_at?: undefined;
+        project_id?: undefined;
+        api_origin?: undefined;
+        items?: undefined;
+        counts?: undefined;
+    } | {
+        status: "ready";
+        synced_at: string;
+        project_id: string;
+        api_origin: string;
+        items: {
+            id: string;
+            remote: {
+                id: string;
+                project_id: string;
+                article_id: string;
+                title: string;
+                slug: string;
+                revision: string;
+                generation_status: "running" | "failed" | "pending" | "completed";
+                ready: boolean;
+                narrated: boolean;
+                publication_pending: boolean;
+                shared: boolean;
+                public_on_article: boolean;
+                review_url: string;
+                playback_url: string | null;
+                public_url: string | null;
+                article_public_url: string | null;
+                assets: {
+                    video: boolean;
+                    narrated_video: boolean;
+                    subtitles: boolean;
+                    transcript: boolean;
+                    poster: boolean;
+                };
+                created_at: string;
+                updated_at: string;
+                generated_at: string | null;
+                shared_at: string | null;
+                error: {
+                    code: string;
+                    message: string;
+                } | null;
+                transcript_text?: string | null | undefined;
+                transcript_omitted?: boolean | undefined;
+            } | null;
+            sync_status: "remote_only" | "synced" | "remote_changed" | "unavailable";
+            last_known?: {
+                id: string;
+                project_id: string;
+                article_id: string;
+                title: string;
+                slug: string;
+                revision: string;
+                generation_status: "running" | "failed" | "pending" | "completed";
+                ready: boolean;
+                narrated: boolean;
+                publication_pending: boolean;
+                shared: boolean;
+                public_on_article: boolean;
+                review_url: string;
+                playback_url: string | null;
+                public_url: string | null;
+                article_public_url: string | null;
+                assets: {
+                    video: boolean;
+                    narrated_video: boolean;
+                    subtitles: boolean;
+                    transcript: boolean;
+                    poster: boolean;
+                };
+                created_at: string;
+                updated_at: string;
+                generated_at: string | null;
+                shared_at: string | null;
+                error: {
+                    code: string;
+                    message: string;
+                } | null;
+                transcript_text?: string | null | undefined;
+                transcript_omitted?: boolean | undefined;
+            } | undefined;
+        }[];
+        counts: {
+            remote: number;
+            changed: number;
+            unavailable: number;
+        };
+        instructions: string;
+    }>;
+}
+export {};

package/dist/walkthroughs.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { remoteId } from './schema.js';
+import { parse } from './artifacts.js';
+import { fail } from './errors.js';
+import { requireExecution, resolveAction } from './actions.js';
+export const walkthroughSchema = z.object({
+    id: remoteId, project_id: remoteId, article_id: remoteId, title: z.string(), slug: z.string(),
+    revision: z.string().regex(/^[a-f0-9]{64}$/), generation_status: z.enum(['pending', 'running', 'completed', 'failed']),
+    ready: z.boolean(), narrated: z.boolean(), publication_pending: z.boolean(), shared: z.boolean(), public_on_article: z.boolean(),
+    review_url: z.url(), playback_url: z.url().nullable(), public_url: z.url().nullable(), article_public_url: z.url().nullable(),
+    assets: z.object({ video: z.boolean(), narrated_video: z.boolean(), subtitles: z.boolean(), transcript: z.boolean(), poster: z.boolean() }),
+    created_at: z.iso.datetime(), updated_at: z.iso.datetime(), generated_at: z.iso.datetime().nullable(), shared_at: z.iso.datetime().nullable(),
+    error: z.object({ code: z.string(), message: z.string().max(500) }).nullable(),
+    transcript_text: z.string().max(200_000).nullable().optional(), transcript_omitted: z.boolean().optional(),
+});
+const pageSchema = z.object({ project_id: remoteId, through_id: z.string().regex(/^\d+$/), next_cursor: remoteId.nullable(), walkthroughs: z.array(walkthroughSchema).max(500) });
+const snapshotSchema = z.object({ project_id: remoteId, api_origin: z.url(), items: z.array(z.object({
+        id: remoteId, remote: walkthroughSchema.nullable(), last_known: walkthroughSchema.optional(),
+        sync_status: z.enum(['remote_only', 'synced', 'remote_changed', 'unavailable']),
+    })) });
+export class Walkthroughs {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    async supported() {
+        // Article and walkthrough inspection share the existing read permission.
+        // The additive context flag lets older clients keep their action contract.
+        requireExecution(await resolveAction(this.bridge, 'read_articles'), 'remote');
+        const context = await this.bridge.context();
+        if (!context.walkthrough_sync)
+            fail('server_update_required', 'Update the SupportPages server to inspect video walkthroughs.');
+        return context;
+    }
+    check(item, project) {
+        if (item.project_id !== project)
+            fail('invalid_response', 'The server returned a walkthrough from another project.');
+        for (const value of [item.review_url, item.playback_url]) {
+            if (!value)
+                continue;
+            const url = new URL(value), origin = new URL(this.bridge.api.origin);
+            if (url.username || url.password || url.origin !== origin.origin && !(this.bridge.api.dev && url.hostname === origin.hostname && url.protocol === 'https:'))
+                fail('invalid_response', 'Invalid walkthrough review link.');
+        }
+        return item;
+    }
+    async list(input = {}, context) {
+        context ??= await this.supported();
+        const binding = await this.bridge.binding();
+        if (context.project.id !== binding.project_id)
+            fail('destination_mismatch', 'The project changed while reading walkthroughs.');
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(input))
+            if (value !== undefined)
+                query.set(key, parse(key === 'through_id' ? z.string().regex(/^\d+$/) : remoteId, value));
+        const page = parse(pageSchema, await this.bridge.api.request('GET', `/projects/${binding.project_id}/walkthroughs${query.size ? `?${query}` : ''}`), 'invalid_response');
+        if (page.project_id !== binding.project_id || input.through_id !== undefined && page.through_id !== input.through_id)
+            fail('invalid_response', 'The walkthrough inventory changed project or bounds.');
+        let previous = BigInt(input.after_id ?? '0');
+        for (const item of page.walkthroughs) {
+            this.check(item, binding.project_id);
+            if (BigInt(item.id) <= previous || BigInt(item.id) > BigInt(page.through_id) || input.article_id && item.article_id !== input.article_id)
+                fail('invalid_response', 'Invalid walkthrough inventory page.');
+            previous = BigInt(item.id);
+        }
+        if (page.next_cursor && page.next_cursor !== page.walkthroughs.at(-1)?.id)
+            fail('invalid_response', 'Invalid walkthrough cursor.');
+        return page;
+    }
+    async get(id) {
+        parse(remoteId, id);
+        await this.supported();
+        const binding = await this.bridge.binding();
+        const item = this.check(parse(walkthroughSchema, await this.bridge.api.request('GET', `/projects/${binding.project_id}/walkthroughs/${id}`), 'invalid_response'), binding.project_id);
+        if (item.id !== id)
+            fail('invalid_response', 'The server returned another walkthrough.');
+        return item;
+    }
+    // Called under the project sync lock. The caller commits the combined article
+    // and video snapshot only after both complete inventories have been validated.
+    async refresh(context, previous) {
+        if (!context.walkthrough_sync)
+            return { status: 'unsupported', instructions: 'Update the SupportPages server to sync video walkthroughs.' };
+        const binding = await this.bridge.binding();
+        const prior = snapshotSchema.safeParse(previous);
+        const known = new Map(prior.success && prior.data.project_id === binding.project_id && prior.data.api_origin === binding.api_origin ? prior.data.items.map(item => [item.id, item.remote ?? item.last_known]) : []);
+        const rows = [];
+        let cursor, through;
+        do {
+            const page = await this.list({ after_id: cursor, through_id: through }, context);
+            rows.push(...page.walkthroughs);
+            if (rows.length > 100_000)
+                fail('inventory_truncated', 'Too many walkthroughs to sync. The previous snapshot has been kept.');
+            through = page.through_id;
+            cursor = page.next_cursor ?? undefined;
+        } while (cursor);
+        const items = rows.map(remote => {
+            const before = known.get(remote.id);
+            known.delete(remote.id);
+            return { id: remote.id, remote, sync_status: !before ? 'remote_only' : before.revision === remote.revision ? 'synced' : 'remote_changed' };
+        });
+        for (const [id, last_known] of known)
+            items.push({ id, remote: null, last_known, sync_status: 'unavailable' });
+        return { status: 'ready', synced_at: new Date().toISOString(), project_id: binding.project_id, api_origin: binding.api_origin, items,
+            counts: { remote: rows.length, changed: items.filter(item => item.sync_status === 'remote_changed').length, unavailable: known.size },
+            instructions: 'Current walkthrough metadata is refreshed. Missing videos are unavailable (removed or their article is no longer accessible); last_known is historical. Reads never regenerate or share a video.' };
+    }
+}
+//# sourceMappingURL=walkthroughs.js.map

package/dist/walkthroughs.js.map

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

package/dist/workspace.d.ts

@@ -0,0 +1,14 @@
+export declare class Workspace {
+    root: string;
+    private constructor();
+    static create(root: string): Promise<Workspace>;
+    private contains;
+    resolve(relative: string): Promise<string>;
+    read(relative: string, limit?: number): Promise<NonSharedBuffer>;
+    json(relative: string): Promise<unknown>;
+    exists(relative: string): Promise<boolean>;
+    write(relative: string, data: string | Buffer): Promise<string>;
+    writeJson(relative: string, data: unknown): Promise<string>;
+    list(relative: string): Promise<import("fs").Dirent<string>[]>;
+    lock<T>(fn: () => Promise<T>): Promise<T>;
+}

package/dist/workspace.js

@@ -0,0 +1,127 @@
+import { constants } from 'node:fs';
+import { mkdir, realpath, lstat, open, rename, rm, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fail } from './errors.js';
+export class Workspace {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    static async create(root) {
+        const canonical = await realpath(root);
+        if (!(await lstat(canonical)).isDirectory())
+            fail('invalid_workspace', 'The workspace must be a directory.');
+        return new Workspace(canonical);
+    }
+    contains(p) { const rel = path.relative(this.root, p); return rel === '' || (!rel.startsWith('..' + path.sep) && rel !== '..' && !path.isAbsolute(rel)); }
+    async resolve(relative) {
+        if (path.isAbsolute(relative) || relative.includes('\0'))
+            fail('invalid_path', 'Use a path relative to the configured workspace.');
+        const candidate = path.resolve(this.root, relative);
+        if (!this.contains(candidate))
+            fail('invalid_path', 'Path escapes the configured workspace.');
+        let cursor = this.root;
+        for (const part of path.relative(this.root, candidate).split(path.sep).filter(Boolean)) {
+            cursor = path.join(cursor, part);
+            try {
+                if ((await lstat(cursor)).isSymbolicLink())
+                    fail('invalid_path', 'Artifact and state paths must not contain symlinks.');
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    throw e;
+            }
+        }
+        return candidate;
+    }
+    async read(relative, limit = 2 * 1024 * 1024) {
+        const p = await this.resolve(relative);
+        let file;
+        try {
+            file = await open(p, constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                fail('missing_artifact', `Missing ${relative}`);
+            throw e;
+        }
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size > limit)
+                fail('invalid_artifact', `${relative} is not a regular file within the size limit.`);
+            const data = await file.readFile();
+            if (data.length > limit)
+                fail('invalid_artifact', `${relative} exceeds the size limit.`);
+            return data;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async json(relative) {
+        const data = await this.read(relative);
+        try {
+            return JSON.parse(data.toString('utf8'));
+        }
+        catch {
+            fail('invalid_artifact', `${relative} is not valid JSON.`);
+        }
+    }
+    async exists(relative) { try {
+        await lstat(await this.resolve(relative));
+        return true;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return false;
+        throw e;
+    } }
+    async write(relative, data) {
+        const target = await this.resolve(relative);
+        await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+        await this.resolve(relative);
+        const temp = `${target}.${randomUUID()}.tmp`;
+        const file = await open(temp, 'wx', 0o600);
+        try {
+            await file.writeFile(data);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        try {
+            await rename(temp, target);
+        }
+        finally {
+            await rm(temp, { force: true });
+        }
+        return target;
+    }
+    async writeJson(relative, data) { return this.write(relative, JSON.stringify(data, null, 2) + '\n'); }
+    async list(relative) {
+        if (!await this.exists(relative))
+            return [];
+        return readdir(await this.resolve(relative), { withFileTypes: true });
+    }
+    async lock(fn) {
+        const dir = await this.resolve('.rtfm/supportpages');
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const lock = await this.resolve('.rtfm/supportpages/operation.lock');
+        try {
+            await mkdir(lock);
+        }
+        catch (e) {
+            if (e.code === 'EEXIST')
+                fail('workspace_busy', 'Another operation holds the workspace lock. If its process crashed, remove .rtfm/supportpages/operation.lock after confirming it has stopped.');
+            throw e;
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            await rm(lock, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

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

package/dist/writer-agent.d.ts

@@ -0,0 +1,21 @@
+export declare const writerAgentName = "SupportPages.io";
+export declare const writerAgentType = "supportpages-io";
+/** Claude Code namespaces plugin agents as <plugin>:<agent>. The plugin's MCP
+ * configuration sets SUPPORTPAGES_PLUGIN to the plugin name. */
+export declare const pluginName: string | undefined;
+export declare const writerSubagentType: string;
+export declare const writerPermissionInstruction = "Permission requests take priority over concise reporting and article chat guidance; approval prompts must include the command and access needed. When an operation needs additional permission and the host policy allows requests, use the host native approval mechanism directly with the exact command and a clear reason. A sandbox restriction is not an explicit user denial: request approval rather than immediately reporting failure. Wait for the approval decision and continue only if granted. Do not send a request only to the parent when a native approval prompt is available. If approval is denied, policy forbids requesting it, or this host cannot surface it, stop the blocked action and report permission_blocked to the parent with the failed command, specific cause and recovery needed. Do not retry around a denial, weaken sandbox settings, enable YOLO, or bypass restrictions. Publication consent remains the parent responsibility.";
+export declare const backgroundWriterInstruction = "Background reporting: prioritize completing the article and resolving blockers over silence. After the entrypoint succeeds, notify the parent of startup with run_id and editor_url using the host messaging facility when available. Send concise milestone updates and report blockers immediately; include technical diagnostics needed for recovery instead of hiding them. Native approval prompts are allowed and must not be suppressed. Return a final result with run_id, status and editor_url. Report success only after the required finish command confirms delivery; otherwise report permission_blocked, delivery_pending, upload_failed or the specific failure. The parent handles the final user-facing response and publication consent.";
+export declare const backgroundParentInstruction = "For background articles, supervise the delegated writer until it finishes or needs user intervention. Pass the complete task brief directly to the writer, preserve its task identity and completion notification, and record the successful launch with supportpages_update_run. Show the editor link and say launched unless actual startup is confirmed. Keep the main turn active and use the host agent wait/message facilities to receive progress, approval requests and the final result; do not end the turn merely because launch succeeded. Use bounded waits and concise progress updates rather than rapid status polling. Allow the writer to request native approvals directly when host policy permits. Never treat a sandbox restriction as an explicit user denial. If a background writer cannot surface approval, confirm it has stopped, then continue the same article in the foreground using the MCP recovery instructions and normal approval mechanism; foreground execution does not grant extra permissions. If approval is denied or forbidden by policy, report the specific block and stop that action without bypassing it. Inspect the writer final result and saved run: a host Completed notification alone is not success. For a stopped writer that failed or is permission_blocked before generation finished, record event=failed with stopped=true via supportpages_update_run and show the cause and recovery with the editor link. For a successfully generated writer, call supportpages_complete_article and report the confirmed delivery once. Recover delivery_pending or upload_failed through complete_article without regenerating or marking the writer failed. Keep the writer and MCP session alive. If the host cannot supervise a delegated task, use the foreground fallback; do not launch a separate agent CLI. Honor an explicit user request to return immediately, but explain that approvals or completion may require another user turn on hosts that do not wake the parent.";
+export declare function writerReportingInstruction(background: boolean): string;
+export declare const claudeWriterAgents: {
+    "supportpages-io": {
+        description: string;
+        model: string;
+        prompt: string;
+    };
+};
+export declare const writerLaunchInstruction: string;
+export declare const writerAgentFile: string;
+export declare const codexWriterFile: string;
+export declare const codexWriterLaunchInstruction = "In Codex, use the registered supportpages-io custom agent for this article. Name the delegated task SupportPages.io followed by the article topic. Pass task_brief.codex_model and task_brief.codex_reasoning_effort as the host's model and reasoning_effort spawn overrides when non-null; omit null overrides to use Codex's configured defaults. Start with a fresh context containing the complete task brief so the host can apply explicit model overrides. Pass that brief directly in the subagent tool task/message argument; do not copy it into a temporary JSON file, create a handoff script, or print it through a shell command. The entrypoint already loads the saved run, so launching the writer needs no parent-side file edit. Apply this on retries too. Use background execution only when prefer_background is true. If the host has no custom-agent selector, use a named SupportPages.io task with task_brief.writer_instructions and the same model settings. The installed SupportPages.io coordination skill explicitly requests background delegation when the prepared run prefers it. Do not infer that delegation is disabled merely because the user did not separately request a subagent. If a host tool is missing, a session restriction forbids delegation, or launch fails, explain that specific limitation and run the same task brief in the foreground after stopping any launched writer. Do not silently substitute an unsupported model. Work in the existing directory, without a worktree or a separate agent CLI. The parent handles all MCP calls, previews, draft completion and publication consent; the writer only generates and validates files. Keep the parent's sandbox and permission controls.";

package/dist/writer-agent.js

@@ -0,0 +1,27 @@
+import { articleChatInstruction } from './article-link.js';
+export const writerAgentName = 'SupportPages.io';
+export const writerAgentType = 'supportpages-io';
+/** Claude Code namespaces plugin agents as <plugin>:<agent>. The plugin's MCP
+ * configuration sets SUPPORTPAGES_PLUGIN to the plugin name. */
+export const pluginName = process.env.SUPPORTPAGES_PLUGIN?.trim() || undefined;
+export const writerSubagentType = pluginName ? `${pluginName}:${writerAgentType}` : writerAgentType;
+export const writerPermissionInstruction = 'Permission requests take priority over concise reporting and article chat guidance; approval prompts must include the command and access needed. When an operation needs additional permission and the host policy allows requests, use the host native approval mechanism directly with the exact command and a clear reason. A sandbox restriction is not an explicit user denial: request approval rather than immediately reporting failure. Wait for the approval decision and continue only if granted. Do not send a request only to the parent when a native approval prompt is available. If approval is denied, policy forbids requesting it, or this host cannot surface it, stop the blocked action and report permission_blocked to the parent with the failed command, specific cause and recovery needed. Do not retry around a denial, weaken sandbox settings, enable YOLO, or bypass restrictions. Publication consent remains the parent responsibility.';
+export const backgroundWriterInstruction = 'Background reporting: prioritize completing the article and resolving blockers over silence. After the entrypoint succeeds, notify the parent of startup with run_id and editor_url using the host messaging facility when available. Send concise milestone updates and report blockers immediately; include technical diagnostics needed for recovery instead of hiding them. Native approval prompts are allowed and must not be suppressed. Return a final result with run_id, status and editor_url. Report success only after the required finish command confirms delivery; otherwise report permission_blocked, delivery_pending, upload_failed or the specific failure. The parent handles the final user-facing response and publication consent.';
+export const backgroundParentInstruction = 'For background articles, supervise the delegated writer until it finishes or needs user intervention. Pass the complete task brief directly to the writer, preserve its task identity and completion notification, and record the successful launch with supportpages_update_run. Show the editor link and say launched unless actual startup is confirmed. Keep the main turn active and use the host agent wait/message facilities to receive progress, approval requests and the final result; do not end the turn merely because launch succeeded. Use bounded waits and concise progress updates rather than rapid status polling. Allow the writer to request native approvals directly when host policy permits. Never treat a sandbox restriction as an explicit user denial. If a background writer cannot surface approval, confirm it has stopped, then continue the same article in the foreground using the MCP recovery instructions and normal approval mechanism; foreground execution does not grant extra permissions. If approval is denied or forbidden by policy, report the specific block and stop that action without bypassing it. Inspect the writer final result and saved run: a host Completed notification alone is not success. For a stopped writer that failed or is permission_blocked before generation finished, record event=failed with stopped=true via supportpages_update_run and show the cause and recovery with the editor link. For a successfully generated writer, call supportpages_complete_article and report the confirmed delivery once. Recover delivery_pending or upload_failed through complete_article without regenerating or marking the writer failed. Keep the writer and MCP session alive. If the host cannot supervise a delegated task, use the foreground fallback; do not launch a separate agent CLI. Honor an explicit user request to return immediately, but explain that approvals or completion may require another user turn on hosts that do not wake the parent.';
+export function writerReportingInstruction(background) {
+    return (background ? backgroundWriterInstruction : 'Foreground reporting: include the supplied editor_url in your first progress report and your completion or failure report when available; keep the same link on retries. Keep progress concise and follow the article chat guidance.') + ' ' + writerPermissionInstruction;
+}
+// Shared by the persistent Claude agent and session-scoped --agents definition.
+// Model and permissions inherit the session.
+export const claudeWriterAgents = {
+    [writerAgentType]: {
+        description: 'SupportPages Writer agent for illustrated help articles. Use only after supportpages_prepare_article or supportpages_retry_article returns a task brief.',
+        model: 'inherit',
+        prompt: 'You are the SupportPages.io article writer. Execute the supplied task brief using its workspace, environment, output directory and installed skills. Always run task_brief.entrypoint.shell_command exactly as supplied before reading generation instructions or writing content. The launcher loads the saved run configuration; no environment exports are needed. Run subsequent generation, rendering and validation commands through task_brief.execution so each command gets the correct environment in a fresh shell. If no prepared task brief or entrypoint was supplied, or its check fails, return to the main agent without writing and ask it to call supportpages_prepare_article or supportpages_retry_article. Do not invoke a publicly discovered generation skill or load the private engine directly to bypass preparation. Follow the reporting policy returned by the entrypoint. Provide concise progress and surface blockers promptly in either execution mode. Request native approvals directly when allowed; communication and recovery take priority over silence. Work in the existing application directory without worktree isolation or a new checkout. Produce the complete article and illustrations, then run all required rendering and validation. Do not edit application source, call SupportPages.io MCP tools, upload or publish. The main agent owns the run and handles progress, completion and publication consent. After every required output passes validation, run task_brief.completion.shell_command exactly as supplied and wait for its result before reporting success. This local finish command asks the MCP to perform final validation and draft delivery without giving you credentials. A preview link is not proof of completion. If delivery is pending or fails, return its recovery instructions to the parent; do not claim the article is ready, regenerate, or ask to publish. Only the parent handles publication consent.' + ' ' + writerPermissionInstruction + ' For background execution only: ' + backgroundWriterInstruction + ' ' + articleChatInstruction,
+    },
+};
+export const writerLaunchInstruction = `In Claude Code, select subagent_type="${writerSubagentType}" for the writer, not general-purpose. Set the Agent tool's model parameter to task_brief.claude_model when it is a string; when null, omit the model parameter and inherit the session model. Apply this on initial launches, retries and follow-ups. Do not substitute another model silently if the host cannot use the requested model; explain the limitation. This model setting applies only to Claude Code, not Codex. Begin the task description with "${writerAgentName}" followed by the article topic. Use background execution only when prefer_background is true. If the named agent is unavailable, explain that SupportPages.io setup installs it and Claude may need restarting, then execute the same task brief in the foreground without launching a substitute subagent. If the Agent call returns "Agent type not found", do not repeat that call, prepare a replacement run, or mark the writer started or failed: execute the existing task brief in the foreground and report started only when work actually starts.`;
+export const writerAgentFile = `---\nname: ${writerAgentType}\ndescription: ${JSON.stringify(claudeWriterAgents[writerAgentType].description)}\nmodel: inherit\n---\n\n<!-- Managed by SupportPages: article writer v1 -->\n\n${claudeWriterAgents[writerAgentType].prompt}\n`;
+export const codexWriterFile = `# Managed by SupportPages: article writer v1\nname = ${JSON.stringify(writerAgentType)}\ndescription = ${JSON.stringify(claudeWriterAgents[writerAgentType].description)}\ndeveloper_instructions = ${JSON.stringify(claudeWriterAgents[writerAgentType].prompt)}\n`;
+export const codexWriterLaunchInstruction = `In Codex, use the registered ${writerAgentType} custom agent for this article. Name the delegated task SupportPages.io followed by the article topic. Pass task_brief.codex_model and task_brief.codex_reasoning_effort as the host's model and reasoning_effort spawn overrides when non-null; omit null overrides to use Codex's configured defaults. Start with a fresh context containing the complete task brief so the host can apply explicit model overrides. Pass that brief directly in the subagent tool task/message argument; do not copy it into a temporary JSON file, create a handoff script, or print it through a shell command. The entrypoint already loads the saved run, so launching the writer needs no parent-side file edit. Apply this on retries too. Use background execution only when prefer_background is true. If the host has no custom-agent selector, use a named SupportPages.io task with task_brief.writer_instructions and the same model settings. The installed SupportPages.io coordination skill explicitly requests background delegation when the prepared run prefers it. Do not infer that delegation is disabled merely because the user did not separately request a subagent. If a host tool is missing, a session restriction forbids delegation, or launch fails, explain that specific limitation and run the same task brief in the foreground after stopping any launched writer. Do not silently substitute an unsupported model. Work in the existing directory, without a worktree or a separate agent CLI. The parent handles all MCP calls, previews, draft completion and publication consent; the writer only generates and validates files. Keep the parent's sandbox and permission controls.`;
+//# sourceMappingURL=writer-agent.js.map

package/dist/writer-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-agent.js","sourceRoot":"","sources":["../src/writer-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AACjD,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AACjD;gEACgE;AAChE,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;AAC/E,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI,eAAe,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;AAEpG,MAAM,CAAC,MAAM,2BAA2B,GAAG,66BAA66B,CAAC;AAEz9B,MAAM,CAAC,MAAM,2BAA2B,GAAG,6tBAA6tB,CAAC;AAEzwB,MAAM,CAAC,MAAM,2BAA2B,GAAG,86DAA86D,CAAC;AAE19D,MAAM,UAAU,0BAA0B,CAAC,UAAmB;IAC5D,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,sOAAsO,CAAC,GAAG,GAAG,GAAG,2BAA2B,CAAC;AACjU,CAAC;AAED,gFAAgF;AAChF,6CAA6C;AAC7C,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,CAAC,eAAe,CAAC,EAAE;QACjB,WAAW,EAAE,0JAA0J;QACvK,KAAK,EAAE,SAAS;QAChB,MAAM,EAAE,k4DAAk4D,GAAG,GAAG,GAAG,2BAA2B,GAAG,kCAAkC,GAAG,2BAA2B,GAAG,GAAG,GAAG,sBAAsB;KACjhE;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG,yCAAyC,kBAAkB,mcAAmc,eAAe,+hBAA+hB,CAAC;AAEplC,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,eAAe,kBAAkB,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC,WAAW,CAAC,mFAAmF,kBAAkB,CAAC,eAAe,CAAC,CAAC,MAAM,IAAI,CAAC;AAE/Q,MAAM,CAAC,MAAM,eAAe,GAAG,wDAAwD,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC,WAAW,CAAC,8BAA8B,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;AAErS,MAAM,CAAC,MAAM,4BAA4B,GAAG,gCAAgC,eAAe,knDAAknD,CAAC"}