@zihanw/pi-forge 0.5.4 → 0.5.6

package/assets/readme/PROVENANCE.md

@@ -0,0 +1,95 @@
+# README media
+
+## September 26 Capabilities rename
+
+All ten currently embedded WebUI GIFs (five scenes in each language) were re-recorded from the renamed development source based on `9f3bbb4`. They now show Capabilities and Enable/Disable; `capability-tools.gif` replaces the README reference to `mode-tools.gif`. Historical files, including the old mode and TUI clips, are retained rather than silently relabelled.
+
+Context, Draft diff and Capability recordings use the continuous recorder (1440×900, 15fps exports); Tools and Regex use their dedicated recorder (1200×750, 15fps exports). Both use native pointer actions and continuous X11 capture, with only the disclosed pointer halo. The Capability scene checks actual SDK tool selection `read → read,grep,find → read` and locates both the update and removal in projected context. All projects and sessions are disposable fixtures; no real provider inference, personal history, or cache-hit claim is involved. English/Chinese final keyframes were reviewed against the current UI. The legacy TUI clip was not re-recorded and remains unembedded.
+
+```bash
+npm run build
+PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-capability-media LOCALES=en,zh-CN SCENES=context,diff,capability node scripts/record-readme-continuous.ts
+python3 scripts/export-readme-continuous.py /tmp/forge-capability-media
+PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-tools-regex node scripts/record-readme-tools-regex.ts
+```
+
+Current output scene names are `context`, `diff`, and `capability`; copy reviewed outputs to `context-composition.gif`, `edit-draft-diff.gif`, and `capability-tools.gif` respectively. The sections below document earlier captures, not the current embedded footage.
+
+## September 26 README refresh
+
+The concept header `../pi-forge-header-concept-1.png` is restored unchanged. The duplicate overview screenshot is no longer embedded; old image files remain available. Installation precedes all demo GIFs.
+
+Follow-up review: the TUI clip was removed from both READMEs because its command/status flow did not clearly communicate the benefit. The file and recorder are retained as historical material; the five WebUI feature GIFs remain in use. The personal motivation is now a short opening note, with a prominent optional-subagents link before installation.
+
+Recordings produced for this refresh, based on source `6a197e6` plus the local unpublished-alias removal:
+
+- `tui-quickstart.gif` (retained, not embedded in README): real Pi 0.87.1 TUI, 1000×540, about 12.75s. `/preset use project:read-first` → `/instruction use project:write-tools` → `/instruction status`. This uses synthetic read-first resources, not a verbatim copy of the checked-in example. Real Forge operations change selected tools from read/ls/control to also bash/edit. No model response is shown or implied.
+- `<locale>/tool-selection.gif`: real Policy picker, defaults read/ls → read/ls/grep, Save/Activate, compiled Preview tool list. Permission ceiling already includes grep; this is a default-selection edit, not an authorization bypass. About 12.94s.
+- `<locale>/regex-transforms.gif`: enable a preconfigured outgoing system-text rule, then inspect `SAMPLE_TOKEN` → `[REDACTED]` in Preview. About 8.07s. Only synthetic text is used; no general secret-detection guarantee.
+
+Browser captures use the built product editor and production loopback host/compiler, with an inert command harness and synthetic tools (not a live model session). Native X11 pointer interactions are continuous; the blue halo is a recording aid. 1440×900 masters export to 1200×750/15fps GIFs. Semantic before/after assertions check Preview and tool selection; the browser is restricted to its own editor origin. Parent review confirmed no page errors or external browser requests in either locale, and decoded all five GIFs.
+
+The TUI uses a separate temporary home/agent directory, isolated dark colors with brighter dim text, no session persistence, and a local `offline-demo` model definition with an inert placeholder key. That model is not a real provider. Pi runs offline; a Node preload blocks fetch/socket connections and asserts an empty network-attempt log. Keyframes were manually reviewed for actual command results and tool state; capture action logs are not automated OCR assertions. The terminal has no custom Forge UI or replaced output. Earlier captures showing missing-model warnings were discarded from the published asset and retained only in the local evidence report.
+
+### Reproduce the new recordings
+
+Requires the repository dev dependencies, Pi CLI, Google Chrome, Xvfb, xdotool, ffmpeg, ImageMagick `import`, GNOME Terminal and `dbus-run-session`. Private displays `:192` (browser) and `:196` (terminal) must be free. Recorders create disposable resources and clean up only their own processes. Outputs default to the review directory, not the checked-in images.
+
+```bash
+npm run build
+PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-tools-regex node scripts/record-readme-tools-regex.ts
+PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-tui node scripts/record-readme-tui.ts
+```
+
+Review `/tmp/forge-tools-regex/assets/{en,zh-CN}/` and `/tmp/forge-tui/assets/tui-quickstart.gif` before copying to `assets/readme/`. Masters, keyframes and evidence stay in each output directory. Fixture IDs, timing and hashes vary between runs. These clips prove local editing/management behavior, not provider delivery, model compliance, cache reuse, sandbox isolation or autonomous agent decisions.
+
+## September 24 continuous v3
+
+Captured 2026-09-24 EDT from accepted UI commit `89c6ba2` (development package metadata 0.5.4), using isolated synthetic projects, the built production loopback editor/compiler and, for Mode, a real SDK AgentSession with no remote model requests.
+
+The September 24 capture produced these per-locale files:
+- `editor-overview-v3.png` (retained, no longer in README): editor and compiled Preview (1439×899 browser viewport; the continuous videos/GIFs include the 1px X11 border at 1440×900).
+- `context-composition.gif`: native drag reordering plus project-context toggle, about 14.6s.
+- `mode-tools.gif`: Current session Use → locate → Off → locate removal, about 18.3s. Actual SDK tools `read → read,grep,find → read`; projected instructions/stop notices remain distinct from delivery or cache evidence.
+- `edit-draft-diff.gif`: real keyboard edit followed by Draft diff without resizing, about 13–14s.
+
+GIFs are 1440×900/15fps exports of continuous 30fps x11grab MP4, without time acceleration or stitched state screenshots. The native pointer drives the UI; the blue halo/click pulse is a disclosed recording aid, not a Forge feature. Native dragging's light drag image and actual compile loading states are retained. GIF palette conversion is lossy. Complete MP4/GIF decoding and real browser playback/seek were checked for both languages. No personal resources/credentials/history, model inference, provider/cache claims or user-host restart were involved.
+
+## Reproduce September 24 recordings
+
+Requires the checkout's development dependencies, Xvfb, xdotool, ffmpeg, Google Chrome and Python Pillow. Private display `:192` must be unused. The recorder refuses to use an occupied display, creates disposable fixtures and cleans its own processes/resources. Do not copy output over formal assets without reviewing it.
+
+```bash
+npm run build
+PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-readme-v3 LOCALES=en,zh-CN SCENES=context,diff,capability node scripts/record-readme-continuous.ts
+python3 scripts/export-readme-continuous.py /tmp/forge-readme-v3
+```
+
+Output is `media/<locale>/{context,capability,diff}.{mp4,gif}`, proof images and semantic evidence; `manifest.json` records dimensions/durations/hashes. Copy approved GIFs to the corresponding names above and `context-poster.png` to `editor-overview-v3.png`. New recordings have fresh synthetic session IDs; pixel-identical reproduction is not promised.
+
+## Retained legacy media (not referenced by current README)
+
+Captured on 2026-09-23 from the built 0.5.5-development WebUI (package version still 0.5.4), using the production loopback editor server and compiler with an isolated, synthetic code-review project.
+
+Each locale (`en`, `zh-CN`) has:
+
+- `editor-overview.png`: 1440 × 900, selected instructions beside compiled Preview.
+- `context-toggle.gif`: 1440 × 900, two real, settled UI states in a five-second loop. Clicking the project-context toggle removes/restores the owned example `AGENTS.md` paragraph. This is a sampled-state demonstration, not real-time footage or a latency measurement. No zoom, captions, or drawn/replaced UI.
+- `draft-diff.png`: 1440 × 620, one instruction edit compared with the saved Preset. Token deltas are estimates, not provider usage.
+
+No model requests, credentials, personal presets, real conversation history, or user-host restart were needed. `demo-session` and the project contents are examples; `/tmp/pi-forge-readme-*` is a disposable project. Runtime context-file input is supplied through the harness's public prompt-options boundary; no private SDK state is patched. Browser traffic is restricted to that editor origin. These images demonstrate editing/compilation, not provider delivery, model compliance or cache reuse.
+
+## Reproduce from a repository checkout
+
+Requires the repository's Node development dependencies, system Chrome (or `CHROME_PATH`) and Python with Pillow for GIF encoding. Outputs are local; this does not publish them.
+
+```bash
+npm run build
+PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-readme-capture node scripts/record-readme-media.ts
+# Inspect the captured PNGs before replacing the checked-in media.
+python3 scripts/render-readme-media.py /tmp/forge-readme-capture assets/readme
+npm run check:docs
+npm run check:package
+```
+
+The recorder owns its temporary project/global configuration directories and removes them after use. It never copies user auth files. GIFs use one shared palette and two 2.5-second holds; the encoder validates frame count, loop and dimensions.

package/dist/active-state.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Neutral active-state snapshot/change bus for optional appearance/session
+ * consumers.
+ *
+ * This module is deliberately Pi Pet-agnostic: it publishes only the small,
+ * privacy-preserving scalar contract in the parent implementation contract
+ * (`@zihanw/pi-forge/active-state/v1`). It never carries prompt text, file
+ * paths, tokens, credentials, model configuration, tool policy, or character
+ * data. Consumers are optional and must not affect Forge compilation, tool
+ * policy, or provider behavior.
+ */
+export declare const FORGE_ACTIVE_STATE_SCHEMA_VERSION: "1";
+export declare const FORGE_ACTIVE_STATE_CHANNEL = "@zihanw/pi-forge/active-state/v1";
+export declare const FORGE_ACTIVE_STATE_REQUEST_CHANNEL = "@zihanw/pi-forge/active-state/request/v1";
+/** Hash domain separator from the parent contract. Do not change without a new version. */
+export declare const FORGE_ACTIVE_STATE_PROJECT_KEY_PREFIX = "pi-forge-project-v1\0";
+/**
+ * Scoped resource key grammar from the parent contract. Stricter than the
+ * internal resource grammar (length-bounded, exactly one colon).
+ */
+export declare const FORGE_ACTIVE_STATE_SCOPED_KEY_PATTERN: RegExp;
+/** Opaque lower-hex SHA-256 project key. */
+export declare const FORGE_ACTIVE_STATE_PROJECT_KEY_PATTERN: RegExp;
+/**
+ * Bounded publisher-instance grammar shared with the downstream Pi Pet/Clawd
+ * appearance consumer. UUIDs pass; control characters, path separators, and
+ * other punctuation are rejected so an instance id can never look like a path
+ * or smuggle control bytes across the bus.
+ */
+export declare const FORGE_ACTIVE_STATE_INSTANCE_ID_PATTERN: RegExp;
+export declare const FORGE_ACTIVE_STATE_MAX_SESSION_ID_LENGTH = 1024;
+export declare const FORGE_ACTIVE_STATE_MAX_INSTANCE_ID_LENGTH = 128;
+export interface ForgeActiveStateEvent {
+    schemaVersion: typeof FORGE_ACTIVE_STATE_SCHEMA_VERSION;
+    /** Raw Pi session-manager ID for the session this snapshot belongs to. */
+    sessionId: string;
+    /** UUID refreshed per publisher attach/epoch; retired instances must be ignored. */
+    instanceId: string;
+    /** Monotonic safe integer within one instance. */
+    revision: number;
+    /** Effective scoped prompt-stack key, or null when no stack is active. */
+    stackKey: string | null;
+    /** Compatible applied-profile provenance key, or null (see profile rule). */
+    profileKey: string | null;
+    /** Opaque project key, or null. Never a raw path. */
+    projectKey: string | null;
+}
+export interface ForgeActiveStateRequest {
+    schemaVersion: typeof FORGE_ACTIVE_STATE_SCHEMA_VERSION;
+    /** When present, the publisher only answers for this exact session. */
+    sessionId?: string;
+}
+export interface ActiveStateTransport {
+    emit(channel: string, data: unknown): void;
+    on(channel: string, handler: (data: unknown) => void): () => void;
+}
+export type ActiveStateValidationResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+export interface ForgeActiveStateWorkspaceProfile {
+    profileId: string;
+    scope?: "global" | "project";
+    /** Prompt-stack reference recorded when the profile was applied. */
+    promptStack: string | null;
+}
+export interface ForgeActiveStateWorkspaceView {
+    /** Canonical scoped key of the effective stack, or null when disabled. */
+    stackKey?: string | null;
+    profile?: ForgeActiveStateWorkspaceProfile | undefined;
+}
+export interface ForgeActiveStateSession {
+    sessionId: string;
+    cwd: string;
+}
+export interface ForgeActiveStatePublisherOptions {
+    transport: ActiveStateTransport;
+    /** Pure read of the current effective workspace view. Must never throw. */
+    readWorkspace(): ForgeActiveStateWorkspaceView;
+    /** Test seam; defaults to the OS hostname. */
+    hostname?: string;
+    /** Test seam; defaults to a fresh UUID per attach. */
+    createInstanceId?: () => string;
+}
+export declare function isValidActiveStateSessionId(value: unknown): value is string;
+export declare function isValidActiveStateScopedKey(value: unknown): value is string;
+export declare function isValidActiveStateProjectKey(value: unknown): value is string;
+export declare function isValidActiveStateInstanceId(value: unknown): value is string;
+/**
+ * Opaque project identity from the session working directory. The raw path and
+ * hostname never leave this function; only the 64-char digest crosses the bus.
+ */
+export declare function activeStateProjectKey(cwd: string, hostnameValue?: string): string | null;
+export declare function validateActiveStateRequest(value: unknown): ActiveStateValidationResult<ForgeActiveStateRequest>;
+export declare function validateActiveStateEvent(value: unknown): ActiveStateValidationResult<ForgeActiveStateEvent>;
+/**
+ * Publishes active-state snapshots on the neutral channel and answers
+ * late-subscriber snapshot requests. One publisher instance corresponds to one
+ * attached Pi session identity; a session-id change retires the old instance
+ * (after a final cleared snapshot) and attaches a new instance.
+ */
+export declare class ForgeActiveStatePublisher {
+    private readonly transport;
+    private readonly read;
+    private readonly hostnameValue;
+    private readonly createInstanceId;
+    private sessionValue?;
+    private instanceIdValue?;
+    private revisionValue;
+    private requestUnsubscribe?;
+    private requestListenerAttached;
+    private suspended;
+    constructor(options: ForgeActiveStatePublisherOptions);
+    get attached(): boolean;
+    get sessionId(): string | undefined;
+    get instanceId(): string | undefined;
+    get revision(): number;
+    /**
+     * Pause publication and request replies while a lifecycle restore is in
+     * flight. The workspace publishes several intermediate snapshots during
+     * `restoreBranchScopedRuntime`; emitting those would leak the new workspace
+     * under the old session id before the publisher is rebound. Call
+     * `bindSession` once the restore is complete to resume with the latest
+     * coherent snapshot.
+     */
+    suspend(): void;
+    /** Bind or rebind the Pi session, resume publication, and publish the current snapshot. */
+    bindSession(session: ForgeActiveStateSession): void;
+    /** Publish the current workspace view with a fresh revision. */
+    publish(): void;
+    /**
+     * Emit one final cleared snapshot for the bound session, unregister the
+     * request listener, and detach. Safe to call more than once.
+     */
+    dispose(): void;
+    private ensureRequestListener;
+    private unsubscribeRequest;
+    private onRequest;
+    private buildEvent;
+    private buildClearEvent;
+    private emitEvent;
+    private readSafely;
+    private advanceEpoch;
+}
+//# sourceMappingURL=active-state.d.ts.map

package/dist/active-state.d.ts.map

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