@promptbook/cli 0.114.0-3 → 0.114.0-31

package/apps/agents-server/src/utils/agentReferenceResolver/createUnresolvedAgentReferenceDiagnostics.ts

@@ -5,6 +5,8 @@ import type { BookCommitment } from '../../../../../src/commitments/_base/BookCo
 import type { ParsedCommitment } from '../../../../../src/commitments/_base/ParsedCommitment';
 import { consumeAgentReferenceResolutionIssues } from './AgentReferenceResolutionIssue';
 import { extractAgentReferenceTokens } from './extractAgentReferenceTokens';
+import type { MissingCoreAgentRecovery } from './MissingCoreAgentRecovery';
+import { getEffectiveExplicitFromCommitment } from '../explicitFromCommitment';
 
 /**
  * Monaco-compatible diagnostic payload for unresolved compact agent references.
@@ -39,6 +41,11 @@ export type AgentReferenceDiagnostic = {
      * Optional source label shown by Monaco.
      */
     readonly source?: string;
+
+    /**
+     * Optional marker severity. Missing references use Monaco's default error severity.
+     */
+    readonly severity?: 'error' | 'warning' | 'info' | 'hint';
 };
 
 /**
@@ -48,6 +55,19 @@ export type MissingAgentReference = {
     readonly reference: string;
     readonly token: string;
     readonly commitmentType: BookCommitment;
+
+    /**
+     * Whether the reference is implied by the Book language itself instead of being written in the book.
+     *
+     * A book without any `FROM` commitment implicitly inherits from `@Adam`, so a missing Adam has to be reported
+     * even though no token points at it.
+     */
+    readonly isImplicit?: boolean;
+
+    /**
+     * Reinstatement offered when the missing reference points to one of the bundled core agents.
+     */
+    readonly coreAgentRecovery?: MissingCoreAgentRecovery;
 };
 
 /**
@@ -186,6 +206,7 @@ export async function createUnresolvedAgentReferenceDiagnostics(
 function collectAgentReferenceTokenLocations(agentSource: string_book): Array<AgentReferenceTokenLocation> {
     const parsed = parseAgentSourceWithCommitments(agentSource);
     const sourceLines = agentSource.split(/\r?\n/);
+    const effectiveFromCommitment = getEffectiveExplicitFromCommitment(agentSource);
     const tokenLocations: Array<AgentReferenceTokenLocation> = [];
 
     for (let commitmentIndex = 0; commitmentIndex < parsed.commitments.length; commitmentIndex++) {
@@ -194,6 +215,12 @@ function collectAgentReferenceTokenLocations(agentSource: string_book): Array<Ag
             continue;
         }
 
+        // A parent is singular: only the final FROM participates in resolution, so diagnostics must not report an
+        // overridden reference as missing. The Book editor separately marks every duplicate FROM with an explanation.
+        if (commitment.type === 'FROM' && effectiveFromCommitment?.lineIndex !== commitment.lineNumber - 1) {
+            continue;
+        }
+
         const startLineNumber = commitment.lineNumber;
         const nextCommitmentStartLine = parsed.commitments[commitmentIndex + 1]?.lineNumber ?? sourceLines.length + 1;
         const endLineNumber = resolveCommitmentEndLine(sourceLines, startLineNumber, nextCommitmentStartLine - 1);

package/apps/agents-server/src/utils/agentReferenceResolver/resolveCoreAgentAwareMissingReferences.ts

@@ -0,0 +1,156 @@
+import { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES } from '../../../../../servers';
+import { normalizeAgentName } from '../../../../../src/book-2.0/agent-source/normalizeAgentName';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { resolveDefaultAgentsStatus, type CoreAgentReport } from '../defaultAgents/resolveDefaultAgentsStatus';
+import { isImplicitAdamInheritance } from '../explicitFromCommitment';
+import type { MissingAgentReference } from './createUnresolvedAgentReferenceDiagnostics';
+import type { MissingCoreAgentRecovery } from './MissingCoreAgentRecovery';
+
+/**
+ * Dependencies needed to enrich unresolved references with bundled-core-agent recovery.
+ *
+ * @private utility of Agents Server agent-reference diagnostics
+ */
+export type ResolveCoreAgentAwareMissingReferencesOptions = {
+    /**
+     * Agent source currently edited in the Book editor.
+     */
+    readonly agentSource: string_book;
+
+    /**
+     * Unresolved compact references already detected in `agentSource`.
+     */
+    readonly missingAgentReferences: ReadonlyArray<MissingAgentReference>;
+
+    /**
+     * Whether the current user is allowed to reinstate the missing core agents.
+     */
+    readonly isReinstateAllowed: boolean;
+};
+
+/**
+ * Extends unresolved compact references of one book with bundled-core-agent recovery.
+ *
+ * Two things are added here:
+ *
+ * 1. A reference naming a bundled core agent is marked as recoverable, because such an agent should be reinstated
+ *    from its bundled book instead of being created empty from scratch.
+ * 2. A book without any explicit `FROM` implicitly inherits from `@Adam`, so a missing Adam is reported right away
+ *    even though no token in the book points at it.
+ *
+ * @param options - Current book, already-detected missing references, and the reinstate permission.
+ * @returns Missing references carrying core-agent recovery, with the implicit `@Adam` ancestor first when missing.
+ *
+ * @private utility of Agents Server agent-reference diagnostics
+ */
+export async function resolveCoreAgentAwareMissingReferences(
+    options: ResolveCoreAgentAwareMissingReferencesOptions,
+): Promise<ReadonlyArray<MissingAgentReference>> {
+    const { agentSource, missingAgentReferences, isReinstateAllowed } = options;
+    const isAdamImplicitlyInherited = isImplicitAdamInheritance(agentSource);
+
+    if (!isAdamImplicitlyInherited && missingAgentReferences.length === 0) {
+        return missingAgentReferences;
+    }
+
+    const missingCoreAgents = await resolveMissingCoreAgents();
+
+    if (missingCoreAgents.length === 0) {
+        return missingAgentReferences;
+    }
+
+    const coreAgentRecovery: MissingCoreAgentRecovery = {
+        missingCoreAgentTitles: missingCoreAgents.map((missingCoreAgent) => missingCoreAgent.title),
+        isReinstateAllowed,
+    };
+    const recoverableMissingAgentReferences = missingAgentReferences.map((missingAgentReference) =>
+        findMissingCoreAgent(missingCoreAgents, missingAgentReference.reference)
+            ? { ...missingAgentReference, coreAgentRecovery }
+            : missingAgentReference,
+    );
+
+    if (!isAdamImplicitlyInherited) {
+        return recoverableMissingAgentReferences;
+    }
+
+    const missingAdamAgent = findMissingCoreAgent(missingCoreAgents, CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES.ADAM);
+
+    if (!missingAdamAgent || hasMissingAgentReferenceFor(recoverableMissingAgentReferences, missingAdamAgent)) {
+        return recoverableMissingAgentReferences;
+    }
+
+    return [
+        createImplicitAdamMissingReference(missingAdamAgent, coreAgentRecovery),
+        ...recoverableMissingAgentReferences,
+    ];
+}
+
+/**
+ * Resolves which bundled core agents are absent from the current server.
+ *
+ * Presence comes from the same status the Core Agents admin page renders, so the panel linking to that page can never
+ * disagree with it. Implicit inheritance always loads Adam from this very server, so a federated namesake elsewhere
+ * must not count as present.
+ *
+ * @returns Reports of the bundled core agents that are missing, in bundled order.
+ */
+async function resolveMissingCoreAgents(): Promise<ReadonlyArray<CoreAgentReport>> {
+    try {
+        const { coreAgents } = await resolveDefaultAgentsStatus();
+        return coreAgents.filter((coreAgent) => !coreAgent.isPresent);
+    } catch (error) {
+        console.warn('[AgentReferenceResolver] Failed to resolve the bundled core agent status:', error);
+        return [];
+    }
+}
+
+/**
+ * Finds the missing bundled core agent one reference points to.
+ *
+ * @param missingCoreAgents - Bundled core agents currently missing on this server.
+ * @param reference - Raw reference payload, for example `Adam` or `adam`.
+ * @returns Matching missing core agent, or `undefined` when the reference names something else.
+ */
+function findMissingCoreAgent(
+    missingCoreAgents: ReadonlyArray<CoreAgentReport>,
+    reference: string,
+): CoreAgentReport | undefined {
+    const normalizedReference = normalizeAgentName(reference);
+    return missingCoreAgents.find((missingCoreAgent) => missingCoreAgent.agentName === normalizedReference);
+}
+
+/**
+ * Checks whether one missing core agent is already reported by an explicit reference written in the book.
+ *
+ * @param missingAgentReferences - Missing references detected in the book.
+ * @param missingCoreAgent - Missing core agent to look for.
+ * @returns True when the book already shows a card for that agent.
+ */
+function hasMissingAgentReferenceFor(
+    missingAgentReferences: ReadonlyArray<MissingAgentReference>,
+    missingCoreAgent: CoreAgentReport,
+): boolean {
+    return missingAgentReferences.some(
+        (missingAgentReference) => normalizeAgentName(missingAgentReference.reference) === missingCoreAgent.agentName,
+    );
+}
+
+/**
+ * Creates the missing-reference entry standing for the implicit `FROM @Adam` ancestor.
+ *
+ * @param missingAdamAgent - Report of the missing Adam core agent.
+ * @param coreAgentRecovery - Reinstatement offered for the missing core agents.
+ * @returns Missing reference shown exactly like an explicitly referenced agent that was not found.
+ */
+function createImplicitAdamMissingReference(
+    missingAdamAgent: CoreAgentReport,
+    coreAgentRecovery: MissingCoreAgentRecovery,
+): MissingAgentReference {
+    return {
+        reference: missingAdamAgent.title,
+        token: `{${missingAdamAgent.title}}`,
+        commitmentType: 'FROM',
+        isImplicit: true,
+        coreAgentRecovery,
+    };
+}

package/apps/agents-server/src/utils/bookLanguageDocumentation/createBookLanguageDocumentationPdfResponse.ts

@@ -81,23 +81,25 @@ export function createBookLanguageDocumentationPdfHtml(
     const branding = getPromptbookExportBranding();
     const documentHtml = groupHtmlHeadingSections(highlightBookCodeBlocksInHtml(renderMarkdown(markdown)));
 
-    return `<!doctype html>
-<html lang="${escapeHtml(language)}">
-<head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    ${createPromptbookBrandingMetaTags(branding)}
-    <title>${escapeHtml(branding.productName)} - Book Language Manual</title>
-    <style>${createBookLanguageDocumentationPdfStyles()}</style>
-</head>
-<body>
-    <main>
-        ${createPromptbookBrandingHeader(branding, logoDataUrl)}
-        ${documentHtml}
-        ${createPromptbookBrandingFooter(branding)}
-    </main>
-</body>
-</html>`;
+    return spaceTrim(
+        (block) => `<!doctype html>
+    <html lang="${block(escapeHtml(language))}">
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        ${block(createPromptbookBrandingMetaTags(branding))}
+        <title>${block(escapeHtml(branding.productName))} - Book Language Manual</title>
+        <style>${block(createBookLanguageDocumentationPdfStyles())}</style>
+    </head>
+    <body>
+        <main>
+            ${block(createPromptbookBrandingHeader(branding, logoDataUrl))}
+            ${block(documentHtml)}
+            ${block(createPromptbookBrandingFooter(branding))}
+        </main>
+    </body>
+    </html>`,
+    );
 }
 
 /**

package/apps/agents-server/src/utils/chatMessageChips/createAnsweredMessageChipToolCalls.ts

@@ -0,0 +1,49 @@
+import type { ToolCall } from '@promptbook-local/types';
+import type { AgentMessageProjectChange } from '../../../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+import type { AgentMessageTouchedExternalSource } from '../../../../../src/utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+import type { AppliedAgentPlannedMessageCommand } from '../localChatRunner/applyLocalAgentPlannedMessageCommands';
+import { createPlannedMessageChipToolCalls } from './createPlannedMessageChipToolCalls';
+import { createTouchedExternalSourceChipToolCalls } from './createTouchedExternalSourceChipToolCalls';
+import { createTouchedProjectChipToolCalls } from './createTouchedProjectChipToolCalls';
+
+/**
+ * Creates every extra chip shown below one answered chat message.
+ *
+ * This is the single place deciding what an answer shows besides its text: the wake-ups it
+ * planned, the projects it worked with — including what it changed in them — and the sources
+ * outside the agent it touched. The chips
+ * travel as tool calls of the assistant message, so they are visible in every chat view —
+ * including external chats such as email, whose outbound reply is rendered from the message text
+ * alone and therefore stays unchanged.
+ *
+ * @param options - Owning agent plus what the answered message planned and touched.
+ * @returns Tool calls rendered as chips below the answer, in a stable order.
+ */
+export async function createAnsweredMessageChipToolCalls(options: {
+    readonly agentPermanentId: string;
+    readonly appliedPlannedMessageCommands: ReadonlyArray<AppliedAgentPlannedMessageCommand>;
+    readonly touchedProjectNames: ReadonlyArray<string>;
+    readonly projectChanges?: ReadonlyArray<AgentMessageProjectChange>;
+    readonly touchedExternalSources: ReadonlyArray<AgentMessageTouchedExternalSource>;
+    readonly createdAt?: NonNullable<ToolCall['createdAt']>;
+}): Promise<ReadonlyArray<ToolCall>> {
+    const createdAt = options.createdAt || (new Date().toISOString() as NonNullable<ToolCall['createdAt']>);
+    const projectChipToolCalls = await createTouchedProjectChipToolCalls({
+        agentPermanentId: options.agentPermanentId,
+        touchedProjectNames: options.touchedProjectNames,
+        projectChanges: options.projectChanges || [],
+        createdAt,
+    });
+
+    return [
+        ...projectChipToolCalls,
+        ...createTouchedExternalSourceChipToolCalls({
+            touchedExternalSources: options.touchedExternalSources,
+            createdAt,
+        }),
+        ...createPlannedMessageChipToolCalls({
+            appliedCommands: options.appliedPlannedMessageCommands,
+            createdAt,
+        }),
+    ];
+}

package/apps/agents-server/src/utils/chatMessageChips/createPlannedMessageChipToolCalls.ts

@@ -0,0 +1,44 @@
+import type { ToolCall } from '@promptbook-local/types';
+import {
+    CANCEL_TIMEOUT_TOOL_CALL_NAME,
+    SET_TIMEOUT_TOOL_CALL_NAME,
+} from '../../../../../src/book-components/Chat/utils/timeoutToolCallPresentation';
+import type { AppliedAgentPlannedMessageCommand } from '../localChatRunner/applyLocalAgentPlannedMessageCommands';
+
+/**
+ * Prefix of the idempotency keys identifying planned-message chips.
+ */
+const PLANNED_MESSAGE_CHIP_IDEMPOTENCY_PREFIX = 'planned-message';
+
+/**
+ * Creates the timeout chips of the message that planned, re-planned, or cancelled a wake-up.
+ *
+ * The chat already renders `set_timeout` and `cancel_timeout` tool calls as timeout chips with a
+ * detail popup, so one planned message becomes exactly one such tool call instead of a second
+ * timeout presentation. A re-planned message keeps the scheduling chip, because it still ends with a
+ * wake-up waiting ahead.
+ *
+ * @param options - Planned-message commands applied for one answered message.
+ * @returns Timeout tool calls shown as chips below the answer.
+ */
+export function createPlannedMessageChipToolCalls(options: {
+    readonly appliedCommands: ReadonlyArray<AppliedAgentPlannedMessageCommand>;
+    readonly createdAt: NonNullable<ToolCall['createdAt']>;
+}): ReadonlyArray<ToolCall> {
+    return options.appliedCommands.map(({ command, result }) => ({
+        name: result.action === 'cancel' ? CANCEL_TIMEOUT_TOOL_CALL_NAME : SET_TIMEOUT_TOOL_CALL_NAME,
+        arguments: {
+            ...(command.milliseconds === undefined ? {} : { milliseconds: command.milliseconds }),
+            ...(command.cronExpression === undefined ? {} : { cronExpression: command.cronExpression }),
+            ...(command.startsAt === undefined ? {} : { startsAt: command.startsAt }),
+            ...(command.endsAt === undefined ? {} : { endsAt: command.endsAt }),
+            ...(command.maxRunCount === undefined ? {} : { maxRunCount: command.maxRunCount }),
+            ...(command.message === undefined ? {} : { message: command.message }),
+            ...(command.timeoutId === undefined ? {} : { timeoutId: command.timeoutId }),
+        },
+        result,
+        state: 'COMPLETE',
+        idempotencyKey: `${PLANNED_MESSAGE_CHIP_IDEMPOTENCY_PREFIX}-${result.action}-${result.timeoutId}`,
+        createdAt: options.createdAt,
+    }));
+}

package/apps/agents-server/src/utils/chatMessageChips/createTouchedExternalSourceChipToolCalls.ts

@@ -0,0 +1,39 @@
+import type { ToolCall } from '@promptbook-local/types';
+import { EXTERNAL_SOURCE_TOOL_CALL_NAME } from '../../../../../src/book-components/Chat/utils/externalSourceToolCall';
+import type { AgentMessageTouchedExternalSource } from '../../../../../src/utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+
+/**
+ * Prefix of the idempotency keys identifying touched-external-source chips.
+ */
+const TOUCHED_EXTERNAL_SOURCE_CHIP_IDEMPOTENCY_PREFIX = 'external-source';
+
+/**
+ * Creates the external-source chips of one answered message.
+ *
+ * An external source is reported by the runner once the answering harness reached beyond the
+ * agent itself — an integration such as Gmail, a website, or a web search — so the chat always
+ * tells which outside services and addresses one answer really involved. Work the agent does
+ * only inside itself reaches this with an empty list and therefore shows no chip.
+ *
+ * @param options - External sources the answer touched.
+ * @returns External-source tool calls shown as chips below the answer.
+ */
+export function createTouchedExternalSourceChipToolCalls(options: {
+    readonly touchedExternalSources: ReadonlyArray<AgentMessageTouchedExternalSource>;
+    readonly createdAt: NonNullable<ToolCall['createdAt']>;
+}): ReadonlyArray<ToolCall> {
+    return options.touchedExternalSources.map((touchedExternalSource) => ({
+        name: EXTERNAL_SOURCE_TOOL_CALL_NAME,
+        arguments: {
+            kind: touchedExternalSource.kind,
+            name: touchedExternalSource.name,
+            ...(touchedExternalSource.url === undefined ? {} : { url: touchedExternalSource.url }),
+        },
+        result: touchedExternalSource,
+        state: 'COMPLETE',
+        idempotencyKey: `${TOUCHED_EXTERNAL_SOURCE_CHIP_IDEMPOTENCY_PREFIX}-${
+            touchedExternalSource.kind
+        }-${touchedExternalSource.name.toLowerCase()}`,
+        createdAt: options.createdAt,
+    }));
+}

package/apps/agents-server/src/utils/chatMessageChips/createTouchedProjectChipResult.ts

@@ -0,0 +1,45 @@
+import type { AgentProjectToolCallResult } from '../../../../../src/book-components/Chat/utils/agentProjectToolCall';
+import type { AgentMessageProjectChange } from '../../../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+import { buildAgentProjectProfileHref } from '../agentProjects/agentProjectHrefs';
+import { resolveAgentProjectInfo } from '../agentProjects/resolveAgentProjectInfo';
+import { resolveAgentProjectRuntimeStatus } from '../agentProjects/resolveAgentProjectRuntimeStatus';
+import { formatResourceBytes } from '../resourceMonitor/formatResourceMonitorValue';
+
+/**
+ * Builds everything one project chip shows about the project it stands for.
+ *
+ * The payload is assembled from the very same sources as the project page — project metadata,
+ * runtime state and the formatted project size — so a chip and the page it links to can never
+ * describe one project differently. It travels inside the chat message, which keeps the chip
+ * popup readable in every chat surface without asking the server again.
+ *
+ * @param options - Project identity and what the answered message changed in it.
+ * @returns Chip payload, or `null` when the project no longer exists.
+ */
+export async function createTouchedProjectChipResult(options: {
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+    readonly projectChange: AgentMessageProjectChange | null;
+}): Promise<AgentProjectToolCallResult | null> {
+    const project = await resolveAgentProjectInfo(options.agentPermanentId, options.projectName);
+
+    if (!project) {
+        return null;
+    }
+
+    const runtimeStatus = await resolveAgentProjectRuntimeStatus(options.agentPermanentId, project.projectName);
+
+    return {
+        projectName: project.projectName,
+        displayName: project.displayName,
+        projectHref: buildAgentProjectProfileHref(options.agentPermanentId, project.projectName),
+        isRunning: runtimeStatus.isRunning,
+        runtimeStatusLabel: runtimeStatus.statusLabel,
+        sizeLabel: formatResourceBytes(project.sizeBytes),
+        fileCount: project.fileCount,
+        isGitRepository: project.isGitRepository,
+        ...(project.description ? { description: project.description } : {}),
+        ...(runtimeStatus.projectUrl ? { projectUrl: runtimeStatus.projectUrl } : {}),
+        ...(options.projectChange ? { change: options.projectChange } : {}),
+    };
+}

package/apps/agents-server/src/utils/chatMessageChips/createTouchedProjectChipToolCalls.ts

@@ -0,0 +1,109 @@
+import type { ToolCall } from '@promptbook-local/types';
+import { AGENT_PROJECT_TOOL_CALL_NAME } from '../../../../../src/book-components/Chat/utils/agentProjectToolCall';
+import type { AgentMessageProjectChange } from '../../../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+import { isSafeAgentProjectPathSegment } from '../agentProjects/agentProjectsPaths';
+import { createTouchedProjectChipResult } from './createTouchedProjectChipResult';
+
+/**
+ * Prefix of the idempotency keys identifying touched-project chips.
+ */
+const TOUCHED_PROJECT_CHIP_IDEMPOTENCY_PREFIX = 'agent-project';
+
+/**
+ * Creates the project chips of one answered message.
+ *
+ * A project is reported by the runner once the answering harness viewed or edited any of its
+ * files, and every project the answer really committed something into is included as well — a
+ * changed project was obviously worked with, even when nothing in the harness log said so.
+ * Projects that no longer exist are skipped.
+ *
+ * @param options - Owning agent, the project directory names its answer touched and what it changed.
+ * @returns Project tool calls shown as chips below the answer.
+ */
+export async function createTouchedProjectChipToolCalls(options: {
+    readonly agentPermanentId: string;
+    readonly touchedProjectNames: ReadonlyArray<string>;
+    readonly projectChanges: ReadonlyArray<AgentMessageProjectChange>;
+    readonly createdAt: NonNullable<ToolCall['createdAt']>;
+}): Promise<ReadonlyArray<ToolCall>> {
+    const changeByProjectName = new Map(
+        options.projectChanges.map((projectChange) => [projectChange.projectName.toLowerCase(), projectChange]),
+    );
+    const projectChipToolCalls = await Promise.all(
+        resolveChippedProjectNames(options.touchedProjectNames, options.projectChanges).map((projectName) =>
+            createTouchedProjectChipToolCall({
+                agentPermanentId: options.agentPermanentId,
+                projectName,
+                projectChange: changeByProjectName.get(projectName.toLowerCase()) || null,
+                createdAt: options.createdAt,
+            }),
+        ),
+    );
+
+    return projectChipToolCalls.filter((projectChipToolCall): projectChipToolCall is ToolCall =>
+        Boolean(projectChipToolCall),
+    );
+}
+
+/**
+ * Resolves which projects deserve a chip, keeping the order in which they were reported.
+ *
+ * @param touchedProjectNames - Projects the harness log showed as viewed or edited.
+ * @param projectChanges - Projects the answer committed something into.
+ * @returns Unique, safe project directory names.
+ *
+ * @private function of `createTouchedProjectChipToolCalls`
+ */
+function resolveChippedProjectNames(
+    touchedProjectNames: ReadonlyArray<string>,
+    projectChanges: ReadonlyArray<AgentMessageProjectChange>,
+): ReadonlyArray<string> {
+    const chippedProjectNames = new Map<string, string>();
+
+    for (const projectName of [
+        ...touchedProjectNames,
+        ...projectChanges.map((projectChange) => projectChange.projectName),
+    ]) {
+        if (!isSafeAgentProjectPathSegment(projectName) || chippedProjectNames.has(projectName.toLowerCase())) {
+            continue;
+        }
+
+        chippedProjectNames.set(projectName.toLowerCase(), projectName);
+    }
+
+    return [...chippedProjectNames.values()];
+}
+
+/**
+ * Creates the chip of one touched project.
+ *
+ * @param options - Owning agent, one touched project and what the answer changed in it.
+ * @returns Project tool call, or `null` when the project no longer exists.
+ *
+ * @private function of `createTouchedProjectChipToolCalls`
+ */
+async function createTouchedProjectChipToolCall(options: {
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+    readonly projectChange: AgentMessageProjectChange | null;
+    readonly createdAt: NonNullable<ToolCall['createdAt']>;
+}): Promise<ToolCall | null> {
+    const projectChipResult = await createTouchedProjectChipResult({
+        agentPermanentId: options.agentPermanentId,
+        projectName: options.projectName,
+        projectChange: options.projectChange,
+    });
+
+    if (!projectChipResult) {
+        return null;
+    }
+
+    return {
+        name: AGENT_PROJECT_TOOL_CALL_NAME,
+        arguments: { projectName: projectChipResult.projectName },
+        result: projectChipResult,
+        state: 'COMPLETE',
+        idempotencyKey: `${TOUCHED_PROJECT_CHIP_IDEMPOTENCY_PREFIX}-${projectChipResult.projectName.toLowerCase()}`,
+        createdAt: options.createdAt,
+    };
+}

package/apps/agents-server/src/utils/chatTasksAdmin.ts

@@ -72,6 +72,15 @@ export type AdminChatTaskRecord = {
     workerId: string | null;
     queueName: string | null;
 
+    /**
+     * True when the task runs in the agent's own goal chat instead of a chat started by a user.
+     *
+     * Goal-chat tasks keep their normal kind (they really are chat completions / chat timeouts) and
+     * are only flagged, so they stay in the regular task streams while remaining distinguishable
+     * from user-invoked work.
+     */
+    isAgentGoalTask?: boolean;
+
     /**
      * Registered server this task belongs to, when the source task is bound to one server or the
      * VPS-wide superadmin aggregation adds the owning server.

package/apps/agents-server/src/utils/createAgentWithDefaultVisibility.ts

@@ -1,5 +1,6 @@
 import type { AgentBasicInformation, AgentCollection, string_book } from '@promptbook-local/types';
 import type { CreateAgentInput } from '../../../../src/collection/agent-collection/CreateAgentInput';
+import { recordAgentGoalChatLifecycleNote } from './agentGoalChat/recordAgentGoalChatLifecycleNote';
 import { assignAgentOwner } from './agentOwnership';
 import { parseAgentSourceVisibility } from './agentVisibility';
 import { getDefaultAgentVisibility } from './getDefaultAgentVisibility';
@@ -40,5 +41,12 @@ export async function createAgentWithDefaultVisibility(
         await assignAgentOwner(createdAgent.permanentId, userId);
     }
 
+    await recordAgentGoalChatLifecycleNote({
+        event: 'CREATED',
+        agentPermanentId: createdAgent.permanentId,
+        agentName: createdAgent.agentName,
+        agentSource,
+    });
+
     return createdAgent;
 }

package/apps/agents-server/src/utils/createWellKnownAgentUrl.ts

@@ -0,0 +1,17 @@
+import { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES } from '../../../../servers';
+import type { string_agent_url } from '../../../../src/_packages/types.index';
+import { createLocalAgentUrl } from './localAgentRouteReferences';
+
+/**
+ * Creates the local profile URL of one bundled well-known agent.
+ *
+ * @param localServerUrl - Public origin of the owning Agents Server.
+ * @param agentName - Logical well-known agent identifier.
+ * @returns Canonical URL for the bundled agent.
+ */
+export function createWellKnownAgentUrl(
+    localServerUrl: string,
+    agentName: keyof typeof CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES,
+): string_agent_url {
+    return createLocalAgentUrl(localServerUrl, CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES[agentName]);
+}

package/apps/agents-server/src/utils/cronExpression/CronExpression.ts

@@ -0,0 +1,63 @@
+/**
+ * Number of fields in a standard minute-based cron expression.
+ *
+ * @private constant of `cronExpression`
+ */
+export const CRON_EXPRESSION_FIELD_COUNT = 5;
+
+/**
+ * Parsed values of one cron field.
+ *
+ * @private type of `cronExpression`
+ */
+export type CronExpressionField = {
+    /**
+     * Accepted numeric values for this field.
+     */
+    readonly values: ReadonlySet<number>;
+
+    /**
+     * Whether the field is the unrestricted `*` wildcard.
+     */
+    readonly isWildcard: boolean;
+};
+
+/**
+ * Parsed five-field cron expression.
+ *
+ * @private type of `cronExpression`
+ */
+export type ParsedCronExpression = {
+    readonly minute: CronExpressionField;
+    readonly hour: CronExpressionField;
+    readonly dayOfMonth: CronExpressionField;
+    readonly month: CronExpressionField;
+    readonly dayOfWeek: CronExpressionField;
+};
+
+/**
+ * Parser configuration of one cron field.
+ *
+ * @private type of `cronExpression`
+ */
+export type CronExpressionFieldOptions = {
+    /**
+     * Field name used in validation errors.
+     */
+    readonly name: string;
+
+    /**
+     * Lowest accepted value.
+     */
+    readonly minimum: number;
+
+    /**
+     * Highest accepted value.
+     */
+    readonly maximum: number;
+
+    /**
+     * Whether `7` is an alias of Sunday, which is only true for the day-of-week field.
+     */
+    readonly isSevenAllowedForSunday?: boolean;
+};