@timurproko/a1 0.2.2-dev.611 → 0.2.3-dev.651

package/README.md

@@ -3,10 +3,10 @@
 ## Install
 
 ```sh
-npx -y @timurproko/a1-install                           # release
-npx -y @timurproko/a1-install --develop                 # develop
-npx -y @timurproko/a1-install --develop 107             # preview number
-npx -y @timurproko/a1-install --develop 0.1.8-dev.107   # exact preview
+npm x -y -- @timurproko/a1-install                           # release
+npm x -y -- @timurproko/a1-install --develop                 # develop
+npm x -y -- @timurproko/a1-install --develop 107             # preview number
+npm x -y -- @timurproko/a1-install --develop 0.1.8-dev.107   # exact preview
 ```
 
 ## Use
@@ -14,7 +14,7 @@ npx -y @timurproko/a1-install --develop 0.1.8-dev.107   # exact preview
 ```sh
 a1                                      # launch A1 (profile: ~/.a1/agent)
 a1 help                                 # show all commands
-a1 version                              # show the version
+a1 version                              # show the current and latest versions
 a1 pi                                   # vanilla Pi oracle: ~/.pi/agent
 ```
 
@@ -22,12 +22,14 @@ Update:
 
 ```sh
 a1 update                               # install the release
-a1 update --models                      # refresh A1's model catalogs
 a1 update --develop                     # install develop
 a1 update --develop 107                 # install preview 107
 a1 update --develop 0.1.8-dev.107       # install that exact preview
+a1 update --models                      # refresh A1's model catalogs
 ```
 
+On interactive startup A1 checks, at most once a day, whether a newer release exists on its own channel and shows an `Update Available` notice with the command to run. It never installs anything. Turn it off with the `Update check` setting (Generic section), or set `A1_SKIP_VERSION_CHECK=1`; it is also skipped when `PI_OFFLINE` or `CI` is set, or when output is not a terminal. The check reads the public npm registry, or `npm_config_registry` when set.
+
 ## Extensions
 
 ```sh
@@ -46,13 +48,13 @@ a1 update npm:pi-mcp-adapter           # update one
 ## Develop
 
 ```sh
-npm run doctor                          # report Node, npm, git, Rust, and dependency readiness
 npm ci                                  # install exact locked dependencies
 npm run build                           # compile TypeScript and the process guardian into dist
 npm start                               # build and launch a source `a1`
 npm run start:pi                        # build and launch a source `a1 pi`
 npm run test:fast                       # typecheck + fast suite (alias: npm test)
 npm run test:full                       # complete non-physical suite
+npm run doctor                          # report Node, npm, git, Rust, and dependency readiness
 ```
 
 ## Publish
@@ -69,5 +71,11 @@ npm run develop                         # request the preview publish
 npm run release -- patch               # 0.1.8-dev -> 0.1.8
 npm run release -- minor               # 0.1.8-dev -> 0.2.0
 npm run release -- major               # 0.1.8-dev -> 1.0.0
-npm run release -- 0.4.0               # an exact stable version
+npm run release -- 0.4.0               # prepare an exact stable version
 ```
+
+The command creates the draft, starts validation of its source, prints the progress
+link, and waits. When validation passes it prints the draft link: edit the Pi-style
+`## [version] - YYYY-MM-DD` changelog, then choose
+GitHub's native **Publish release** button: that publishes both packages to npm. If
+publication fails before npm, the Release returns to draft so you can publish it again.

package/bin/pinned-pi-public.js

@@ -2,16 +2,23 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, posix, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+/** @type {string | undefined} */
+let configuredRoot;
+
 /**
  * Bind the generated facade to the package reached through Pi's public entry.
  * @param {string | URL} entryUrl
  */
 export function configurePinnedPiPublicPackageEntry(entryUrl) {
-  const root = dirname(dirname(fileURLToPath(entryUrl)));
+  const root = resolve(dirname(dirname(fileURLToPath(entryUrl))));
   const manifest = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
   if (manifest.name !== "@earendil-works/pi-coding-agent" || typeof manifest.version !== "string") {
     throw new Error("pinned Pi public package identity is invalid");
   }
+  if (configuredRoot !== undefined && configuredRoot !== root) {
+    throw new Error("pinned Pi public package identity cannot change after configuration");
+  }
+  configuredRoot = root;
   process.env.PI_PACKAGE_DIR = root;
   return { root, version: manifest.version };
 }
@@ -55,9 +62,9 @@ export function resolvePinnedPiImport(specifier) {
 }
 
 function pinnedRoot() {
-  const root = process.env.PI_PACKAGE_DIR;
-  if (!root || !existsSync(resolve(root, "package.json"))) throw new Error("pinned Pi public package directory is not configured");
-  return resolve(root);
+  if (configuredRoot === undefined) throw new Error("pinned Pi public package directory is not configured");
+  if (!existsSync(resolve(configuredRoot, "package.json"))) throw new Error("pinned Pi public package directory is unavailable");
+  return configuredRoot;
 }
 
 /**

package/dist/app/session-shell/index.d.ts

@@ -2,6 +2,6 @@ export { ClipboardDiagnosticCapture } from "./clipboard-diagnostics.js";
 export { ContextualPromptSuggestionController, samePromptSuggestionIdentity } from "./prompt-suggestion-controller.js";
 export type { ContextualPromptSuggestionControllerOptions, ContextualPromptSuggestionSurface } from "./prompt-suggestion-controller.js";
 export { OwnedUiSessionShell, OwnedUiSessionShellRoot, formatSessionResumeCommand, quoteCommandArgument } from "./session-shell.js";
-export type { OwnedUiSessionShellOptions, OwnedUiShellDiagnosticOptions, OwnedUiShellEngineOptions, OwnedUiShellHistoryOptions, OwnedUiShellPresentationOptions, OwnedUiShellSkillsOptions, OwnedUiShellSuggestionOptions, SessionResumeCommandMetadata, } from "./session-shell.js";
+export type { OwnedUiSessionShellOptions, OwnedUiShellDiagnosticOptions, OwnedUiShellEngineOptions, OwnedUiShellHistoryOptions, OwnedUiShellPresentationOptions, OwnedUiShellPromptImagesOptions, OwnedUiShellSkillsOptions, OwnedUiShellSuggestionOptions, SessionResumeCommandMetadata, } from "./session-shell.js";
 export { STREAM_PRESENTATION_INTERVAL_MS, StreamPresentationCoalescer } from "./stream-presentation-coalescer.js";
 export type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";

package/dist/app/session-shell/paste-executor.js

@@ -181,7 +181,12 @@ export function startPasteExecutor(content, signal, phase = () => { }, helper, p
                 fail();
         }
         catch (error) {
-            fail(error instanceof ImageAttachmentError ? error.code : "paste-unavailable");
+            if (error instanceof ImageAttachmentError) {
+                failure = error;
+                cancel();
+            }
+            else
+                fail("paste-unavailable");
         }
     });
     child.once("error", () => fail());

package/dist/app/session-shell/prompt-chips.d.ts

@@ -17,6 +17,7 @@ export declare class PromptChipStore {
         readonly isolated?: boolean;
         readonly onEvent?: (event: PasteEvent) => void;
         readonly preparation?: Omit<PastePreparationClientOptions, "onEvent">;
+        readonly imageLimit?: () => number;
     });
     /** Forks the spare paste helper so the session's first paste does not pay for helper startup. */
     warm(): void;
@@ -31,10 +32,17 @@ export declare class PromptChipStore {
     reconcileDraft(text: string): void;
     resetPastes(text: string): string;
     dispose(): Promise<void>;
+    imageLimitState(text: string): {
+        readonly count: number;
+        readonly limit: number;
+        readonly corrected: boolean;
+    };
     transformPastedContent(content: PiShellClipboardContent, currentText?: string): string;
     /** Hide provisional clipboard identities until the read identifies an actual image. */
     hiddenRanges(line: string): readonly PiShellEditorTextRange[];
     atomicRanges(line: string): readonly PiShellEditorTextRange[];
+    unsentRanges(line: string): readonly PiShellEditorTextRange[];
+    omitUnsentImages(text: string): string;
     hyperlinkRanges(text: string): readonly {
         start: number;
         end: number;

package/dist/app/session-shell/prompt-chips.js

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import path from "node:path";
 import { canonicalizeClipboardImage } from "./clipboard-image.js";
-import { assertImageEncodedSize, assertPromptImages, canonicalPromptChipMatches, ImageAttachmentError, replaceCanonicalPromptChips, } from "../../contracts/owned-ui/index.js";
+import { assertImageEncodedSize, assertPromptImages, canonicalPromptChipMatches, DEFAULT_PROMPT_IMAGE_LIMIT, ImageAttachmentError, replaceCanonicalPromptChips, } from "../../contracts/owned-ui/index.js";
 import { ImagePreparationClient } from "./image-preparation-client.js";
 import { preparePasteText } from "./paste-text-preparation.js";
 import { pathChipTag } from "./path-chip-presentation.js";
@@ -13,18 +13,29 @@ function imageChipIdentifier(tag) {
     const match = IMAGE_CHIP_IDENTIFIER_PATTERN.exec(tag);
     return match === null ? null : match[1] ?? null;
 }
+function rejectedImageMarker(marker, error) {
+    return error.code === "image-count" ? marker : marker.replace("screenshot-", "failed-");
+}
+function referencesPasteMarker(text, entry) {
+    return text.includes(entry.marker)
+        || (entry.error !== undefined && entry.replacement !== undefined && text.includes(entry.replacement));
+}
 /** Owns semantic chips and bounded pending paste references; cancels background work on reset or disposal. */
 export class PromptChipStore {
     #chips = new Map();
     // Invariant: clearing the editor never recycles a recoverable text chip's identity.
     #textCounter = 0;
     #pending = new Map();
+    // Invariant: count-rejected images keep the standard chip label, so retain their identities after draft cleanup.
+    #countRejectedImages = new Set();
     #preparation = new ImagePreparationClient();
     #stopping = new Set();
     #isolated;
     #provisionalOwners = new Map();
     #ownedChipTags = new Map();
+    #imageLimit;
     constructor(options = {}) {
+        this.#imageLimit = options.imageLimit ?? (() => DEFAULT_PROMPT_IMAGE_LIMIT);
         this.#isolated = options.isolated
             ? new PastePreparationClient({ ...options.preparation, ...(options.onEvent === undefined ? {} : { onEvent: options.onEvent }) })
             : undefined;
@@ -44,8 +55,9 @@ export class PromptChipStore {
             entry.kind = content?.kind === "image" ? "image" : "text";
             if (content?.kind === "image") {
                 onImage();
-                if (this.#imageCount(currentText) >= 8)
-                    throw new ImageAttachmentError("image-count");
+                const imageLimit = this.#imageLimit();
+                if (this.#imageCount(currentText) >= imageLimit)
+                    throw new ImageAttachmentError("image-count", imageLimit);
             }
             return content;
         });
@@ -60,9 +72,11 @@ export class PromptChipStore {
                 entry.error = error instanceof ImageAttachmentError ? error : new ImageAttachmentError("image-codec");
                 if (entry.error.code !== "image-canceled" && entry.references === 0)
                     onError(entry.error);
-                return marker.replace("screenshot-", "failed-");
+                return rejectedImageMarker(marker, entry.error);
             }).then(replacement => {
                 entry.replacement = replacement;
+                if (entry.error?.code === "image-count")
+                    this.#countRejectedImages.add(replacement);
                 return replacement;
             }) };
         this.#pending.set(marker, entry);
@@ -86,8 +100,9 @@ export class PromptChipStore {
         }, () => {
             entry.kind = "image";
             onImage();
-            if (this.#imageCount(currentText) >= 8)
-                throw new ImageAttachmentError("image-count");
+            const imageLimit = this.#imageLimit();
+            if (this.#imageCount(currentText) >= imageLimit)
+                throw new ImageAttachmentError("image-count", imageLimit);
         }, () => { entry.kind = "text"; });
         entry = { marker, job, references: 0, kind: "unknown", completion: job.result.catch(error => {
                 this.#finishChipOwnership(owner, false);
@@ -97,8 +112,13 @@ export class PromptChipStore {
                     entry.kind = "image";
                 if (entry.error.code !== "image-canceled" && entry.references === 0)
                     onError(entry.error);
-                return entry.kind === "image" ? marker.replace("screenshot-", "failed-") : "";
-            }).then(replacement => { entry.replacement = replacement; return replacement; }) };
+                return entry.kind === "image" ? rejectedImageMarker(marker, entry.error) : "";
+            }).then(replacement => {
+                entry.replacement = replacement;
+                if (entry.error?.code === "image-count")
+                    this.#countRejectedImages.add(replacement);
+                return replacement;
+            }) };
         entry.onComplete = () => {
             this.#finishChipOwnership(owner, job.isCurrent() && entry.error === undefined);
             job.complete();
@@ -152,7 +172,7 @@ export class PromptChipStore {
     }
     reconcileDraft(text) {
         for (const entry of this.#pending.values()) {
-            if (entry.references === 0 && !text.includes(entry.marker) && !text.includes(entry.marker.replace("screenshot-", "failed-"))) {
+            if (entry.references === 0 && !referencesPasteMarker(text, entry)) {
                 entry.job.cancel();
                 if (entry.replacement !== undefined) {
                     entry.onComplete?.();
@@ -180,13 +200,21 @@ export class PromptChipStore {
         await Promise.all([this.#preparation.dispose(), this.#isolated?.dispose(), ...this.#stopping]);
         this.#chips.clear();
         this.#pending.clear();
+        this.#countRejectedImages.clear();
         this.#provisionalOwners.clear();
         this.#ownedChipTags.clear();
     }
+    imageLimitState(text) {
+        const limit = this.#imageLimit();
+        const rejectedCountMarker = canonicalPromptChipMatches(text).some(match => this.#countRejectedImages.has(match.text))
+            || [...this.#pending.values()].some(entry => entry.error?.code === "image-count" && referencesPasteMarker(text, entry));
+        const count = this.#imageCount(text);
+        return { count, limit, corrected: count <= limit && !rejectedCountMarker };
+    }
     #imageCount(text) {
         const tags = new Set([...this.#chips.values()].filter(chip => chip.kind === "image" && text.includes(chip.tag)).map(chip => chip.tag));
         for (const entry of this.#pending.values()) {
-            if (entry.kind !== "text" && (text.includes(entry.marker) || text.includes(entry.marker.replace("screenshot-", "failed-")))) {
+            if (entry.kind !== "text" && entry.error?.code !== "image-count" && referencesPasteMarker(text, entry)) {
                 // Invariant: a ready screenshot can retain its pending label but still occupies only one slot.
                 tags.add(entry.replacement ?? entry.marker);
             }
@@ -207,7 +235,7 @@ export class PromptChipStore {
             const image = canonicalizeClipboardImage(content);
             if (image === null)
                 return "";
-            assertPromptImages([...this.prepareSubmission(currentText).images, { type: "image", ...image }]);
+            assertPromptImages([...this.prepareSubmission(currentText).images, { type: "image", ...image }], this.#imageLimit());
             const id = randomBytes(5).toString("hex");
             const tag = `[📷 screenshot-${id}]`;
             this.#chips.set(tag, {
@@ -262,6 +290,15 @@ export class PromptChipStore {
             .filter(match => !match.text.startsWith("[paste #") || this.#chips.has(match.text))
             .map(match => ({ start: match.start, end: match.end }));
     }
+    unsentRanges(line) {
+        return canonicalPromptChipMatches(line)
+            .filter(match => this.#countRejectedImages.has(match.text))
+            .map(match => ({ start: match.start, end: match.end }));
+    }
+    omitUnsentImages(text) {
+        return replaceCanonicalPromptChips(text, match => this.#countRejectedImages.has(match.text)
+            || this.#pendingEntry(match.text)?.error?.code === "image-count" ? "" : match.text);
+    }
     hyperlinkRanges(text) {
         const ranges = [];
         for (const chip of this.#chips.values()) {
@@ -292,7 +329,7 @@ export class PromptChipStore {
      * chips carrying the original attachment bytes.
      */
     prepareHistoryText(text) {
-        return this.#replaceResolvable(text, false, false).text.trim();
+        return this.#replaceResolvable(this.omitUnsentImages(text), false, false).text.trim();
     }
     /**
      * Extract the image chip attachments referenced by an editor draft in occurrence order,
@@ -396,6 +433,7 @@ export class PromptChipStore {
     }
     prepareSubmission(text) {
         const expanded = this.#replaceResolvable(text, true);
+        assertPromptImages(expanded.images, this.#imageLimit());
         return { text: expanded.text, images: expanded.images };
     }
     #replaceResolvable(text, includeImages, omitImages = false) {
@@ -419,9 +457,13 @@ export class PromptChipStore {
         // Invariant: scan only draft tokens (and resolved reservation tokens), never emitted payloads.
         const expanded = replaceCanonicalPromptChips(text, match => {
             const tag = match.text;
-            const entry = this.#pending.get(tag) ?? this.#pending.get(tag.replace("failed-", "screenshot-"));
+            if (this.#countRejectedImages.has(tag))
+                return "";
+            const entry = this.#pendingEntry(tag);
             if (entry === undefined)
                 return resolveChip(tag);
+            if (entry.error?.code === "image-count")
+                return "";
             if (includeImages && entry.error !== undefined)
                 throw entry.error;
             if (includeImages && entry.replacement === undefined)
@@ -430,6 +472,9 @@ export class PromptChipStore {
         });
         return { text: expanded, images };
     }
+    #pendingEntry(tag) {
+        return this.#pending.get(tag) ?? [...this.#pending.values()].find(entry => entry.error !== undefined && entry.replacement === tag);
+    }
     #claimChip(tag, owner, created) {
         if (owner === undefined) {
             this.#provisionalOwners.delete(tag);

package/dist/app/session-shell/session-shell-root.d.ts

@@ -1,6 +1,7 @@
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
 import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
 import type { PiTuiPointerSurface } from "../../integrations/pi/tui-runtime/contracts.js";
-import type { UiRouteHost } from "../../ui/apps/contracts.js";
+import type { UiRouteHost, UiRouteInput } from "../../ui/apps/contracts.js";
 import type { TranscriptViewportFrame, TranscriptViewportFrameDescriptor } from "../../ui/components/transcript-viewport.js";
 import type { PiEngineAdapter } from "../../integrations/pi/engine/adapter.js";
 import type { PiWorkflowMessage, PiWorkflowResult } from "../../integrations/pi/engine/workflows.js";
@@ -35,6 +36,12 @@ export interface OwnedUiShellEngineOptions {
      * every other route continues to the pinned workflow table unchanged.
      */
     readonly routeHost?: UiRouteHost;
+    /** One product-owned route presented after the first usable frame and any startup modal. */
+    readonly startupRoute?: {
+        readonly route: string;
+        readonly input?: UiRouteInput;
+        readonly onClosed?: () => void | Promise<void>;
+    };
     /** Bare A1 selects the owned bounded viewport; comparison profiles stay pinned. */
     readonly sessionLayout?: "pinned" | "custom-viewport";
 }
@@ -110,6 +117,11 @@ export interface OwnedUiShellDiagnosticOptions {
     /** Test seams for isolated paste preparation: an in-process starter, or the forked helper's entry. */
     readonly pastePreparation?: Omit<PastePreparationClientOptions, "onEvent" | "spareIdleMs">;
 }
+/** Live prompt-image admission policy supplied only by the bare-A1 profile. */
+export interface OwnedUiShellPromptImagesOptions {
+    readonly limit: () => number;
+    readonly onChange: (listener: () => void) => () => void;
+}
 /** The skills presentation choice: collapse the per-skill commands into one skills command or expand them. */
 export interface OwnedUiShellSkillsOptions {
     readonly presentation: () => "collapse" | "expand";
@@ -121,6 +133,8 @@ export interface OwnedUiSessionShellOptions {
     readonly presentation?: OwnedUiShellPresentationOptions;
     readonly history?: OwnedUiShellHistoryOptions;
     readonly suggestions?: OwnedUiShellSuggestionOptions;
+    /** Supplied only to bare A1; absent retains the fixed eight-image comparison policy. */
+    readonly promptImages?: OwnedUiShellPromptImagesOptions;
     /** Supplied only to the bare-A1 composition; absent keeps the pinned per-skill command list. */
     readonly skills?: OwnedUiShellSkillsOptions;
     readonly diagnostics?: OwnedUiShellDiagnosticOptions;
@@ -160,6 +174,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly captureClipboardPaste?: () => PasteSource;
         readonly pasteDiagnostics?: (event: PasteEvent) => void;
         readonly pastePreparation?: Omit<PastePreparationClientOptions, "onEvent">;
+        readonly promptImageLimit?: () => number;
         readonly skillsPresentation?: () => "collapse" | "expand";
     }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: PiShellExtensionRendererResolver, sessionLayout?: "pinned" | "custom-viewport", imageAssets?: PiShellImageAssetResolver);
     setEditorPaddingX(padding: number): void;
@@ -169,6 +184,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     setMermaidRenderingMode(mode: "off" | "final" | "streaming"): void;
     setImagePresentation(showImages: boolean, imageWidthCells: number): void;
     prepareHistoryText(text: string): string;
+    omitUnsentPromptImages(text: string): string;
     rehydrateHistoryText(text: string, resolveImage: (id: string) => import("../../contracts/owned-ui/index.js").PromptHistoryImageSidecarAttachment | null): string;
     imageChipAttachmentsFromEditor(text: string): {
         readonly id: string;
@@ -180,6 +196,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         };
     }[];
     preparePromptSubmission(text: string): PreparedPrompt;
+    reconcilePromptImageLimitNotice(text?: string): boolean;
     hasPendingPastes(text: string): boolean;
     waitForPromptPastes(text: string, signal: AbortSignal): Promise<PreparedPrompt>;
     resetPendingPastes(): void;
@@ -244,8 +261,8 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     transcriptComponent(id: string): PiShellTranscriptComponentPort | undefined;
     exitTranscript(width: number): string;
     appendWorkflowStatus(message: string): void;
-    appendWorkflowMessage(message: PiWorkflowMessage): void;
-    appendWorkflowResult(result: PiWorkflowResult): void;
+    appendWorkflowMessage(message: PiWorkflowMessage, errorCode?: ImageAttachmentError["code"]): void;
+    appendWorkflowResult(result: PiWorkflowResult, errorCode?: ImageAttachmentError["code"]): void;
     appendDaxnuts(): void;
     toggleThinkingVisibility(): void;
     get toolsExpanded(): boolean;
@@ -255,6 +272,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     setExtensionFooter(component: PiShellComponentPort | null): void;
     setExtensionStatus(key: string, text: string | undefined): void;
     setExtensionWorking(message: string | undefined, visible?: boolean): void;
+    beginImageSubmissionStatus(): () => void;
     hotkeysPresentation(): PiShellHotkeysPresentation;
     resetWorkflowPresentation(): void;
     resetExtensionUi(): void;