@promptbook/cli 0.114.0-3 → 0.114.0-30

package/src/{commitments/USE_BROWSER → scrapers/_common/utils}/fetchUrlContent.ts

@@ -1,9 +1,9 @@
 import { spaceTrim } from 'spacetrim';
-import type { LlmExecutionTools } from '../../execution/LlmExecutionTools';
-import { $provideFilesystemForNode } from '../../scrapers/_common/register/$provideFilesystemForNode';
-import type { ScraperSourceHandler } from '../../scrapers/_common/Scraper';
-import { promptbookFetch } from '../../scrapers/_common/utils/promptbookFetch';
-import { WebsiteScraper } from '../../scrapers/website/WebsiteScraper';
+import type { LlmExecutionTools } from '../../../execution/LlmExecutionTools';
+import { $provideFilesystemForNode } from '../register/$provideFilesystemForNode';
+import type { ScraperSourceHandler } from '../Scraper';
+import { WebsiteScraper } from '../../website/WebsiteScraper';
+import { promptbookFetch } from './promptbookFetch';
 
 /**
  * Fetches and scrapes content from a URL (SERVER-SIDE ONLY)
@@ -15,13 +15,12 @@ import { WebsiteScraper } from '../../scrapers/website/WebsiteScraper';
  * 4. Returns the scraped markdown content
  *
  * WARNING: This function should NOT be used directly in browser environments.
- * For browser environments, use fetchUrlContentViaBrowser which proxies through
- * the Agents Server API endpoint at /api/scrape
+ * For browser environments, proxy the request through the Agents Server API endpoint at /api/scrape
  *
  * @param url The URL to fetch and scrape
  * @returns Markdown content from the URL
  *
- * @private internal utility for USE BROWSER commitment
+ * @private internal scraping utility
  */
 export async function fetchUrlContent(url: string): Promise<string> {
     try {
@@ -137,4 +136,4 @@ export async function fetchUrlContent(url: string): Promise<string> {
     }
 }
 
-// Note: [🟢] Code for Node browser-fetch helper [fetchUrlContent](src/commitments/USE_BROWSER/fetchUrlContent.ts) should never be published into packages that could be imported into browser environment
+// Note: [🟢] Code for Node fetch-and-scrape helper [fetchUrlContent](src/scrapers/_common/utils/fetchUrlContent.ts) should never be published into packages that could be imported into browser environment

package/src/utils/agent-message-runtime/AgentMessageProjectChange.ts

@@ -0,0 +1,183 @@
+/**
+ * One file an answered agent message created, edited or deleted inside one project.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageProjectChangedFile = {
+    /**
+     * Path of the file relative to the project root, using `/` separators.
+     */
+    readonly path: string;
+
+    /**
+     * Count of lines added to the file.
+     */
+    readonly insertionCount: number;
+
+    /**
+     * Count of lines removed from the file.
+     */
+    readonly deletionCount: number;
+};
+
+/**
+ * Everything answering one single message changed inside one agent project.
+ *
+ * Each agent project is a git repository and every answer which modifies it is committed there
+ * automatically, so this describes exactly one such commit — the trace of what one message really
+ * did to one project, which a chat can show below the answer that did it.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageProjectChange = {
+    /**
+     * Directory name of the changed project inside the agent `projects/` folder.
+     */
+    readonly projectName: string;
+
+    /**
+     * Full hash of the commit holding the changes of this message.
+     */
+    readonly commitHash: string;
+
+    /**
+     * ISO 8601 timestamp when the changes were committed.
+     */
+    readonly committedAt: string;
+
+    /**
+     * Files the message changed, ordered as git reports them.
+     */
+    readonly changedFiles: ReadonlyArray<AgentMessageProjectChangedFile>;
+
+    /**
+     * Count of lines added across all changed files.
+     */
+    readonly insertionCount: number;
+
+    /**
+     * Count of lines removed across all changed files.
+     */
+    readonly deletionCount: number;
+
+    /**
+     * Unified diff of the commit, shortened when the change is too large to carry into a chat.
+     */
+    readonly diff: string;
+
+    /**
+     * Whether `diff` holds only the beginning of the real diff.
+     */
+    readonly isDiffTruncated: boolean;
+};
+
+/**
+ * Validates one already-parsed JSON value as a project change.
+ *
+ * @param value - Raw serialized project change.
+ * @returns The typed project change, or `null` when the value does not match the expected shape,
+ * so consumers can silently skip foreign or malformed entries.
+ *
+ * @private internal utility of the agent-message runtime
+ */
+export function normalizeAgentMessageProjectChange(value: unknown): AgentMessageProjectChange | null {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+
+    const candidate = value as Partial<AgentMessageProjectChange>;
+    if (!isNonEmptyString(candidate.projectName) || !isNonEmptyString(candidate.commitHash)) {
+        return null;
+    }
+
+    if (!isNonEmptyString(candidate.committedAt) || !Number.isFinite(Date.parse(candidate.committedAt))) {
+        return null;
+    }
+
+    if (!Array.isArray(candidate.changedFiles)) {
+        return null;
+    }
+
+    const changedFiles = candidate.changedFiles.map((changedFile) =>
+        normalizeAgentMessageProjectChangedFile(changedFile),
+    );
+    if (changedFiles.some((changedFile) => changedFile === null)) {
+        return null;
+    }
+
+    if (!isChangeCount(candidate.insertionCount) || !isChangeCount(candidate.deletionCount)) {
+        return null;
+    }
+
+    if (typeof candidate.diff !== 'string' || typeof candidate.isDiffTruncated !== 'boolean') {
+        return null;
+    }
+
+    return {
+        projectName: candidate.projectName.trim(),
+        commitHash: candidate.commitHash.trim(),
+        committedAt: candidate.committedAt,
+        changedFiles: changedFiles as ReadonlyArray<AgentMessageProjectChangedFile>,
+        insertionCount: candidate.insertionCount,
+        deletionCount: candidate.deletionCount,
+        diff: candidate.diff,
+        isDiffTruncated: candidate.isDiffTruncated,
+    };
+}
+
+/**
+ * Validates one already-parsed JSON value as a changed project file.
+ *
+ * @param value - Raw serialized changed file.
+ * @returns The typed changed file, or `null` when the value does not match the expected shape.
+ *
+ * @private internal helper of `normalizeAgentMessageProjectChange`
+ */
+function normalizeAgentMessageProjectChangedFile(value: unknown): AgentMessageProjectChangedFile | null {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+
+    const candidate = value as Partial<AgentMessageProjectChangedFile>;
+    if (!isNonEmptyString(candidate.path)) {
+        return null;
+    }
+
+    if (!isChangeCount(candidate.insertionCount) || !isChangeCount(candidate.deletionCount)) {
+        return null;
+    }
+
+    return {
+        path: candidate.path.trim(),
+        insertionCount: candidate.insertionCount,
+        deletionCount: candidate.deletionCount,
+    };
+}
+
+/**
+ * Checks that one value is a usable non-empty string.
+ *
+ * @param value - Raw serialized value.
+ * @returns Whether the value is a string carrying content.
+ *
+ * @private internal helper of `normalizeAgentMessageProjectChange`
+ */
+function isNonEmptyString(value: unknown): value is string {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * Checks that one value is a line count git could have reported.
+ *
+ * @param value - Raw serialized value.
+ * @returns Whether the value is a non-negative finite number.
+ *
+ * @private internal helper of `normalizeAgentMessageProjectChange`
+ */
+function isChangeCount(value: unknown): value is number {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}

package/src/utils/agent-message-runtime/AgentMessageTouchedExternalSource.ts

@@ -0,0 +1,80 @@
+/**
+ * Category of one external source an answered agent message touched.
+ *
+ * -   `integration` is a third-party service reached through an integration, for example Gmail.
+ * -   `website` is a concrete web address the agent fetched or browsed.
+ * -   `search` is a lookup the agent ran against a web search engine.
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageTouchedExternalSourceKind = 'integration' | 'website' | 'search';
+
+/**
+ * One source outside the agent itself which answering a single message viewed or edited.
+ *
+ * Everything the agent does inside its own folder stays internal and is never described here;
+ * this records only the reach beyond it, so a chat can tell which outside services and websites
+ * one answer really involved.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageTouchedExternalSource = {
+    /**
+     * Category of the touched source.
+     */
+    readonly kind: AgentMessageTouchedExternalSourceKind;
+
+    /**
+     * User-facing name of the source, for example `Gmail`, `example.com` or the search query.
+     */
+    readonly name: string;
+
+    /**
+     * Address of the source, when the touch names a concrete one.
+     */
+    readonly url?: string;
+};
+
+/**
+ * Validates one already-parsed JSON value as a touched external source.
+ *
+ * @param value - Raw serialized source.
+ * @returns The typed source, or `null` when the value does not match the expected shape, so
+ * consumers can silently skip foreign or malformed entries.
+ *
+ * @private internal utility of the agent-message runtime
+ */
+export function normalizeAgentMessageTouchedExternalSource(value: unknown): AgentMessageTouchedExternalSource | null {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+
+    const candidate = value as Partial<AgentMessageTouchedExternalSource>;
+    if (!isAgentMessageTouchedExternalSourceKind(candidate.kind)) {
+        return null;
+    }
+
+    if (typeof candidate.name !== 'string' || candidate.name.trim().length === 0) {
+        return null;
+    }
+
+    return {
+        kind: candidate.kind,
+        name: candidate.name.trim(),
+        ...(typeof candidate.url === 'string' && candidate.url.trim().length > 0 ? { url: candidate.url.trim() } : {}),
+    };
+}
+
+/**
+ * Checks that one value is a known external source category.
+ *
+ * @param value - Raw serialized kind.
+ * @returns Whether the value names one of the supported categories.
+ *
+ * @private internal helper of `normalizeAgentMessageTouchedExternalSource`
+ */
+function isAgentMessageTouchedExternalSourceKind(value: unknown): value is AgentMessageTouchedExternalSourceKind {
+    return value === 'integration' || value === 'website' || value === 'search';
+}

package/src/utils/agent-message-runtime/parseAgentMessageRuntimeLogEvents.ts

@@ -0,0 +1,108 @@
+/**
+ * One string-keyed payload of a coding-harness tool invocation.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+type RuntimeLogToolInput = Record<string, unknown>;
+
+/**
+ * One content block of a Claude Code `stream-json` assistant event.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogContentBlock = {
+    readonly type?: string;
+    readonly text?: string;
+    readonly name?: string;
+    readonly input?: RuntimeLogToolInput;
+};
+
+/**
+ * One file path touched by a Codex `file_change` item.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogFileChange = {
+    readonly path?: string;
+};
+
+/**
+ * Minimal shape of one coding-harness runtime log event.
+ *
+ * The runtime log mixes two harness formats — Claude Code `stream-json` (`type`/`message`) and
+ * Codex JSONL (`type`/`item`) — so both are described by one permissive structure and every
+ * consumer reads only the fields it understands.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogEvent = {
+    readonly type?: string;
+    readonly message?: {
+        readonly content?: ReadonlyArray<AgentMessageRuntimeLogContentBlock>;
+    };
+    readonly item?: {
+        readonly type?: string;
+        readonly command?: string;
+        readonly exit_code?: number | null;
+        readonly changes?: ReadonlyArray<AgentMessageRuntimeLogFileChange>;
+        readonly server?: string;
+        readonly tool?: string;
+        readonly query?: string;
+    };
+};
+
+/**
+ * Parses every structured event out of one coding-harness runtime log.
+ *
+ * The local agent runner streams the answering harness output into a live runtime log file, one
+ * JSON event per line, optionally prefixed by shell noise. Lines without a usable JSON object are
+ * skipped so a partially written or interleaved log never breaks its consumers.
+ *
+ * @param logText - Raw runtime log content.
+ * @returns Structured events in the order they were streamed.
+ * @private internal utility of the agent-message runtime
+ */
+export function parseAgentMessageRuntimeLogEvents(
+    logText: string | null | undefined,
+): ReadonlyArray<AgentMessageRuntimeLogEvent> {
+    if (!logText) {
+        return [];
+    }
+
+    const events: Array<AgentMessageRuntimeLogEvent> = [];
+
+    for (const line of logText.split(/\r?\n/u)) {
+        const event = parseAgentMessageRuntimeLogEvent(line);
+
+        if (event) {
+            events.push(event);
+        }
+    }
+
+    return events;
+}
+
+/**
+ * Parses one runtime log line into a structured event when it embeds JSON.
+ *
+ * @param line - One raw runtime log line.
+ * @returns Structured event, or `null` when the line carries no JSON object.
+ * @private internal helper of `parseAgentMessageRuntimeLogEvents`
+ */
+function parseAgentMessageRuntimeLogEvent(line: string): AgentMessageRuntimeLogEvent | null {
+    const jsonStartIndex = line.indexOf('{');
+    if (jsonStartIndex === -1) {
+        return null;
+    }
+
+    try {
+        const parsedEvent = JSON.parse(line.slice(jsonStartIndex).trim()) as unknown;
+        if (typeof parsedEvent !== 'object' || parsedEvent === null || Array.isArray(parsedEvent)) {
+            return null;
+        }
+
+        return parsedEvent as AgentMessageRuntimeLogEvent;
+    } catch {
+        return null;
+    }
+}

package/src/utils/agent-message-runtime/resolveAgentMessageRuntimeActivity.ts

@@ -1,3 +1,6 @@
+import type { AgentMessageRuntimeLogEvent } from './parseAgentMessageRuntimeLogEvents';
+import { parseAgentMessageRuntimeLogEvents } from './parseAgentMessageRuntimeLogEvents';
+
 /**
  * Maximum length of one user-facing progress activity snippet.
  *
@@ -6,28 +9,69 @@
 const MAX_RUNTIME_ACTIVITY_LENGTH = 160;
 
 /**
- * Minimal shape of one coding-harness `stream-json` event relevant to progress extraction.
- *
- * Only the natural-language assistant narration is read; every other field is ignored so raw
- * tool payloads and technical envelopes never reach the user-facing progress card.
+ * One safe, concrete category of a command emitted by the Codex runtime.
  *
  * @private internal type of agent-message runtime activity
  */
-type RuntimeLogEvent = {
-    readonly type?: string;
-    readonly message?: {
-        readonly content?: ReadonlyArray<{
-            readonly type?: string;
-            readonly text?: string;
-        }>;
-    };
-    readonly item?: {
-        readonly type?: string;
-        readonly command?: string;
-        readonly exit_code?: number | null;
-    };
+type CodexCommandActivity = {
+    readonly pattern: RegExp;
+    readonly running: string;
+    readonly completed: string;
 };
 
+/**
+ * Ordered command categories that can be described truthfully without showing raw commands,
+ * arguments, file names, or other private runtime details.
+ *
+ * The local runner can execute on either Unix or Windows. Keeping the variants together here
+ * ensures that equivalent shell commands yield the same concise status in the chat.
+ *
+ * @private internal constant of agent-message runtime activity
+ */
+const CODEX_COMMAND_ACTIVITIES: ReadonlyArray<CodexCommandActivity> = [
+    {
+        pattern: /(^|\s)(npm\s+(?:run\s+)?test|pnpm\s+(?:run\s+)?test|yarn\s+test|jest|vitest|pytest)\b/u,
+        running: 'Running tests.',
+        completed: 'Finished running tests.',
+    },
+    {
+        pattern: /(^|\s)(npm\s+run\s+build|pnpm\s+(?:run\s+)?build|yarn\s+build|next\s+build)\b/u,
+        running: 'Building the project.',
+        completed: 'Finished building the project.',
+    },
+    {
+        pattern: /(^|\s)(npm|pnpm|yarn)\s+(?:install|add)\b/u,
+        running: 'Installing dependencies.',
+        completed: 'Finished installing dependencies.',
+    },
+    {
+        pattern: /(^|\s)(npm\s+(?:run\s+)?lint|pnpm\s+(?:run\s+)?lint|yarn\s+lint|eslint|prettier)\b/u,
+        running: 'Checking the implementation.',
+        completed: 'Finished checking the implementation.',
+    },
+    {
+        pattern: /(^|\s)git\s+(?:status|diff|log|show)\b/u,
+        running: 'Reviewing changes.',
+        completed: 'Finished reviewing changes.',
+    },
+    {
+        pattern: /(^|\s)(apply_patch|set-content|add-content|out-file|new-item|copy-item|move-item|set-item)\b/u,
+        running: 'Updating relevant files.',
+        completed: 'Finished updating relevant files.',
+    },
+    {
+        pattern:
+            /(^|\s)(ls|find|rg|grep|sed|cat|head|tail|get-content|get-childitem|get-item|select-string|findstr|type)\b/u,
+        running: 'Inspecting relevant files.',
+        completed: 'Finished inspecting relevant files.',
+    },
+    {
+        pattern: /(^|\s)(curl|wget|invoke-webrequest)\b/u,
+        running: 'Looking up information.',
+        completed: 'Finished looking up information.',
+    },
+];
+
 /**
  * Resolves the latest user-friendly activity snippet from a coding-harness runtime log.
  *
@@ -35,9 +79,9 @@ type RuntimeLogEvent = {
  * Claude Code `--output-format stream-json`) into a live runtime log file next to the queued
  * message. This helper extracts the most recent natural-language assistant narration so the
  * durable chat can show what the agent is doing right now instead of a generic thinking
- * placeholder. Only plain assistant text is surfaced; raw tool payloads, JSON envelopes and
- * other technical details are intentionally ignored, and harnesses that do not stream
- * structured text simply resolve to `null` so the caller keeps its existing behavior.
+ * placeholder. Only concrete, safe activity is surfaced; raw tool payloads, JSON envelopes,
+ * and private reasoning are intentionally ignored. When no concrete activity is known, this
+ * resolves to `null` so the caller keeps the browser's rotating generic thinking state.
  *
  * @param logText - Raw runtime log content.
  * @returns Latest human-readable activity snippet, or `null` when none can be resolved.
@@ -50,12 +94,7 @@ export function resolveAgentMessageRuntimeActivity(logText: string | null | unde
 
     let latestActivity: string | null = null;
 
-    for (const line of logText.split(/\r?\n/u)) {
-        const event = parseRuntimeLogEvent(line);
-        if (!event) {
-            continue;
-        }
-
+    for (const event of parseAgentMessageRuntimeLogEvents(logText)) {
         const activity = resolveRuntimeLogEventActivity(event);
         if (activity) {
             latestActivity = activity;
@@ -65,35 +104,12 @@ export function resolveAgentMessageRuntimeActivity(logText: string | null | unde
     return latestActivity === null ? null : truncateRuntimeActivity(latestActivity);
 }
 
-/**
- * Parses one runtime log line into a structured event when it embeds JSON.
- *
- * @private internal helper of `resolveAgentMessageRuntimeActivity`
- */
-function parseRuntimeLogEvent(line: string): RuntimeLogEvent | null {
-    const jsonStartIndex = line.indexOf('{');
-    if (jsonStartIndex === -1) {
-        return null;
-    }
-
-    try {
-        const parsed = JSON.parse(line.slice(jsonStartIndex).trim()) as unknown;
-        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-            return null;
-        }
-
-        return parsed as RuntimeLogEvent;
-    } catch {
-        return null;
-    }
-}
-
 /**
  * Resolves the natural-language assistant narration from one complete assistant event.
  *
  * @private internal helper of `resolveAgentMessageRuntimeActivity`
  */
-function resolveRuntimeLogEventActivity(event: RuntimeLogEvent): string | null {
+function resolveRuntimeLogEventActivity(event: AgentMessageRuntimeLogEvent): string | null {
     const codexActivity = resolveCodexRuntimeLogEventActivity(event);
     if (codexActivity) {
         return codexActivity;
@@ -118,10 +134,13 @@ function resolveRuntimeLogEventActivity(event: RuntimeLogEvent): string | null {
  *
  * Codex reasoning and raw command text deliberately remain private. The event type tells us
  * enough to report a useful action without exposing the internal trace or a command payload.
+ * Reasoning events are intentionally not a progress update: while they are the only signal,
+ * the chat retains its configured generic thinking rotation. Once a concrete action arrives,
+ * it becomes the latest user-facing status instead.
  *
  * @private internal helper of `resolveAgentMessageRuntimeActivity`
  */
-function resolveCodexRuntimeLogEventActivity(event: RuntimeLogEvent): string | null {
+function resolveCodexRuntimeLogEventActivity(event: AgentMessageRuntimeLogEvent): string | null {
     if (!event.item || !isCodexItemEvent(event.type)) {
         return null;
     }
@@ -130,7 +149,7 @@ function resolveCodexRuntimeLogEventActivity(event: RuntimeLogEvent): string | n
 
     switch (event.item.type) {
         case 'reasoning':
-            return isCompleted ? 'Considered the request.' : 'Considering the request.';
+            return null;
         case 'command_execution':
             return resolveCodexCommandActivity(event.item.command, isCompleted, event.item.exit_code);
         case 'file_change':
@@ -164,12 +183,16 @@ function resolveCodexCommandActivity(
     command: string | undefined,
     isCompleted: boolean,
     exitCode: number | null | undefined,
-): string {
+): string | null {
     if (isCompleted && exitCode !== undefined && exitCode !== null && exitCode !== 0) {
         return 'A command needs attention.';
     }
 
     const activity = resolveCodexCommandActivityLabel(command);
+    if (!activity) {
+        return null;
+    }
+
     return isCompleted ? activity.completed : activity.running;
 }
 
@@ -178,30 +201,10 @@ function resolveCodexCommandActivity(
  *
  * @private internal helper of `resolveAgentMessageRuntimeActivity`
  */
-function resolveCodexCommandActivityLabel(command: string | undefined): { running: string; completed: string } {
+function resolveCodexCommandActivityLabel(command: string | undefined): CodexCommandActivity | null {
     const normalizedCommand = command?.toLowerCase() || '';
 
-    if (/(^|\s)(npm\s+(?:run\s+)?test|pnpm\s+(?:run\s+)?test|yarn\s+test|jest|vitest|pytest)\b/u.test(normalizedCommand)) {
-        return { running: 'Running tests.', completed: 'Finished running tests.' };
-    }
-
-    if (/(^|\s)(npm\s+run\s+build|pnpm\s+(?:run\s+)?build|yarn\s+build|next\s+build)\b/u.test(normalizedCommand)) {
-        return { running: 'Building the project.', completed: 'Finished building the project.' };
-    }
-
-    if (/(^|\s)(npm|pnpm|yarn)\s+(?:install|add)\b/u.test(normalizedCommand)) {
-        return { running: 'Installing dependencies.', completed: 'Finished installing dependencies.' };
-    }
-
-    if (/(^|\s)git\s+(?:status|diff|log|show)\b/u.test(normalizedCommand)) {
-        return { running: 'Reviewing changes.', completed: 'Finished reviewing changes.' };
-    }
-
-    if (/(^|\s)(ls|find|rg|grep|sed|cat|head|tail)\b/u.test(normalizedCommand)) {
-        return { running: 'Inspecting relevant files.', completed: 'Finished inspecting relevant files.' };
-    }
-
-    return { running: 'Running a task.', completed: 'Finished a task.' };
+    return CODEX_COMMAND_ACTIVITIES.find((activity) => activity.pattern.test(normalizedCommand)) ?? null;
 }
 
 /**