@zihanw/pi-forge 0.4.1 → 0.5.1

package/dist/workspace.js

@@ -0,0 +1,351 @@
+import { createResourceCatalog } from "./catalog.js";
+import { hasAgentProfileErrors } from "./agent-profile.js";
+import { readAgentProfilesScoped, readGlobalAgentProfiles } from "./repositories/agent-profile.js";
+import { readGlobalPromptStacks, readPromptStacksScoped } from "./repositories/prompt-stack.js";
+import { chooseDefaultStack, isDisabledPromptStackId } from "./loader.js";
+import { formatResourceKey, parseResourceSelector } from "./resource-identity.js";
+import { createForgeExtensionState, reloadForgeExtensions, unloadForgeExtensions } from "./forge-extensions.js";
+import { validateListProfilesRequest, validatePrepareRequest, validatePrepareResponse, validateResolveProfileRequest, validateResolveProfileResponse, ForgeHost, } from "./subagent/host-port.js";
+import { currentSubagentPromptRegistrationCatalog, prepareForgeDelegation, resolveSubagentHostProfile, } from "./subagent-host.js";
+/**
+ * Single owner of the Forge resource graph.
+ *
+ * Owns one coherent, deep-frozen snapshot containing stacks, profiles, active
+ * selection, profile provenance, and extension lifecycle state. All readers
+ * (commands, web UI, lifecycle, tool policy, preview, host port) consume
+ * `snapshot()` instead of separate mutable bags.
+ */
+export class ForgeWorkspace {
+    extensionState = createForgeExtensionState();
+    current;
+    host;
+    get snapshotKnown() {
+        return this.current !== undefined;
+    }
+    reload(cwd, options = {}) {
+        const trusted = options.trusted !== false;
+        const stacks = trusted ? readPromptStacksScoped(cwd) : readGlobalPromptStacks();
+        if (this.extensionDiagnostics.length > 0) {
+            for (const loaded of stacks)
+                loaded.diagnostics.unshift(...this.extensionDiagnostics);
+        }
+        const profiles = trusted ? readAgentProfilesScoped(cwd) : readGlobalAgentProfiles();
+        const active = this.resolveActive(stacks, options);
+        const activeStackId = active ? formatResourceKey(active.key) : (options.activeStackId != null && isDisabledPromptStackId(options.activeStackId) ? "none" : null);
+        const snapshot = {
+            cwd,
+            stacks,
+            profiles,
+            activeStackId,
+            active,
+            lastAppliedProfile: options.lastAppliedProfile ?? this.current?.lastAppliedProfile,
+            extensionDiagnostics: this.extensionDiagnostics,
+            extensionPaths: this.extensionPaths,
+            capturedAt: new Date().toISOString(),
+        };
+        this.current = deepFreeze(structuredClone(snapshot));
+        return this.current;
+    }
+    reloadProfiles(cwd, trusted = true) {
+        if (!this.current)
+            throw new Error("ForgeWorkspace has not been reloaded.");
+        const profiles = trusted ? readAgentProfilesScoped(cwd) : readGlobalAgentProfiles();
+        return this.publish({
+            ...this.current,
+            profiles,
+            capturedAt: new Date().toISOString(),
+        });
+    }
+    async loadExtensions(cwd) {
+        const result = await reloadForgeExtensions(cwd, this.extensionState);
+        this.extensionDiagnostics = result.diagnostics;
+        this.extensionPaths = result.loadedPaths;
+        return result;
+    }
+    disposeExtensions() {
+        const diagnostics = unloadForgeExtensions(this.extensionState);
+        this.extensionDiagnostics = diagnostics;
+        this.extensionPaths = [];
+        return diagnostics;
+    }
+    setActiveStack(id) {
+        if (!this.current)
+            return false;
+        if (!id || isDisabledPromptStackId(id)) {
+            this.publish({
+                ...this.current,
+                activeStackId: "none",
+                active: undefined,
+                capturedAt: new Date().toISOString(),
+            });
+            return true;
+        }
+        const parsed = parseResourceSelector(id);
+        if (!parsed.ok)
+            return false;
+        const found = createResourceCatalog([...this.current.stacks]).resolveSelector(parsed.selector);
+        if (!found)
+            return false;
+        this.publish({
+            ...this.current,
+            activeStackId: formatResourceKey(found.key),
+            active: found,
+            capturedAt: new Date().toISOString(),
+        });
+        return true;
+    }
+    setLastAppliedProfile(profile) {
+        if (!this.current)
+            throw new Error("ForgeWorkspace has not been reloaded.");
+        this.publish({
+            ...this.current,
+            lastAppliedProfile: profile,
+            capturedAt: new Date().toISOString(),
+        });
+    }
+    // Read/write view used by profile-service's AgentProfileApplicationState.
+    get active() {
+        return this.current?.active;
+    }
+    set active(value) {
+        if (!value) {
+            this.setActiveStack(undefined);
+            return;
+        }
+        if (!this.current)
+            throw new Error("ForgeWorkspace has not been reloaded.");
+        this.publish({
+            ...this.current,
+            activeStackId: formatResourceKey(value.key),
+            active: value,
+            capturedAt: new Date().toISOString(),
+        });
+    }
+    get lastAppliedProfile() {
+        return this.current?.lastAppliedProfile;
+    }
+    set lastAppliedProfile(value) {
+        this.setLastAppliedProfile(value);
+    }
+    snapshot() {
+        if (!this.current)
+            throw new Error("ForgeWorkspace has not been reloaded.");
+        return this.current;
+    }
+    /**
+     * Register the host port for the current snapshot. Idempotent: the host is
+     * only started once the first snapshot exists, so `available` never implies
+     * an unloaded workspace. On reload the live host is kept (its generation
+     * only changes via dispose).
+     */
+    startHostPort(transport) {
+        if (!this.current)
+            throw new Error("ForgeWorkspace must be reloaded before starting the host port.");
+        if (this.host?.isLive)
+            return this.host;
+        const host = new ForgeHost(transport, {
+            capabilities: ["listProfiles", "resolveProfile", "prepare"],
+            handle: (operation, payload) => this.operate(operation, payload),
+        });
+        this.host = host;
+        host.start();
+        return host;
+    }
+    /** Invoke the minimal-operation surface against the current snapshot. */
+    operate(operation, payload) {
+        if (operation === "listProfiles")
+            return this.listProfiles(payload);
+        if (operation === "resolveProfile")
+            return this.resolveProfile(payload);
+        if (operation === "prepare")
+            return this.prepare(payload);
+        return { ok: false, error: `Unknown Forge host operation: ${operation}` };
+    }
+    listProfiles(payload) {
+        const validated = validateListProfilesRequest(payload);
+        if (!validated.ok)
+            return { ok: false, error: validated.error };
+        try {
+            const snapshot = this.snapshot();
+            return {
+                ok: true,
+                data: {
+                    profiles: snapshot.profiles.map((loaded) => stripUndefined({
+                        profileId: loaded.profile.id,
+                        scope: loaded.scope,
+                        name: loaded.profile.name,
+                        description: loaded.profile.description,
+                        autoActivate: loaded.profile.autoActivate,
+                        model: { provider: loaded.profile.model.provider, id: loaded.profile.model.id },
+                        thinkingLevel: loaded.profile.thinkingLevel,
+                        promptStack: loaded.profile.promptStack,
+                        usable: !hasAgentProfileErrors(loaded.diagnostics),
+                        diagnostics: loaded.diagnostics,
+                    })),
+                },
+            };
+        }
+        catch (error) {
+            return { ok: false, error: `listProfiles failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    resolveProfile(payload) {
+        const validated = validateResolveProfileRequest(payload);
+        if (!validated.ok)
+            return { ok: false, error: validated.error };
+        const request = validated.data;
+        try {
+            const snapshot = this.resolveProfilePlan(request.profile);
+            const response = { snapshot };
+            const responseValidated = validateResolveProfileResponse(stripUndefined(response));
+            if (!responseValidated.ok)
+                return { ok: false, error: responseValidated.error };
+            return { ok: true, data: stripUndefined(response) };
+        }
+        catch (error) {
+            return { ok: false, error: `resolveProfile failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    /** Host-owned profile resolution returns the immutable profile snapshot artifact. */
+    resolveProfilePlan(profile) {
+        const snapshot = this.snapshot();
+        const parsed = parseResourceSelector(profile);
+        if (!parsed.ok)
+            throw new Error(`Invalid profile selector ${profile}: ${parsed.error}`);
+        const loaded = createResourceCatalog([...snapshot.profiles]).resolveSelector(parsed.selector);
+        if (!loaded)
+            throw new Error(`Unknown profile: ${profile}`);
+        if (hasAgentProfileErrors(loaded.diagnostics))
+            throw new Error(`Profile ${profile} failed loading validation.`);
+        const resolved = resolveSubagentHostProfile(loaded, {
+            promptStacks: snapshot.stacks,
+            registrations: currentSubagentPromptRegistrationCatalog(),
+        });
+        if (!resolved.snapshot)
+            throw new Error(`Profile ${profile} could not be resolved.`);
+        return resolved.snapshot;
+    }
+    prepare(payload) {
+        const validated = validatePrepareRequest(payload);
+        if (!validated.ok)
+            return { ok: false, error: validated.error };
+        const request = validated.data;
+        let response;
+        try {
+            response = stripUndefined(this.preparePlan(request));
+        }
+        catch (error) {
+            return { ok: false, error: `Prepare failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+        const responseValidated = validatePrepareResponse(response);
+        if (!responseValidated.ok)
+            return { ok: false, error: responseValidated.error };
+        return { ok: true, data: response };
+    }
+    /** Host owns profile/stack resolution and prompt compilation. */
+    preparePlan(request) {
+        const snapshot = this.snapshot();
+        const parsed = parseResourceSelector(request.profile);
+        if (!parsed.ok)
+            throw new Error(`Invalid profile selector ${request.profile}: ${parsed.error}`);
+        const loaded = createResourceCatalog([...snapshot.profiles]).resolveSelector(parsed.selector);
+        if (!loaded)
+            throw new Error(`Unknown profile: ${request.profile}`);
+        if (hasAgentProfileErrors(loaded.diagnostics))
+            throw new Error(`Profile ${request.profile} failed loading validation.`);
+        const resolved = resolveSubagentHostProfile(loaded, {
+            promptStacks: snapshot.stacks,
+            registrations: currentSubagentPromptRegistrationCatalog(),
+        });
+        if (!resolved.snapshot)
+            throw new Error(`Profile ${request.profile} could not be resolved for preparation.`);
+        const prepared = prepareForgeDelegation({
+            snapshot: resolved.snapshot,
+            task: request.task,
+            access: request.access,
+            backend: request.backend,
+            cwd: snapshot.cwd,
+        });
+        return {
+            profileId: request.profile,
+            model: { ...request.backend.model },
+            thinkingLevel: request.backend.thinkingLevel,
+            systemPrompt: prepared.systemPrompt,
+            messages: prepared.messages,
+            effectiveToolIds: prepared.effectiveToolIds,
+            effectiveToolNames: prepared.effectiveToolNames,
+            diagnostics: prepared.diagnostics,
+            profileSnapshot: resolved.snapshot,
+            preparedAt: prepared.preparedAt,
+        };
+    }
+    dispose() {
+        this.disposeExtensions();
+        if (this.host?.isLive)
+            this.host.stop();
+        this.host = undefined;
+        this.current = undefined;
+    }
+    resolveActive(stacks, options) {
+        if (options.suppressAutoActivate && options.activeStackId == null)
+            return undefined;
+        if (options.activeStackId != null) {
+            if (isDisabledPromptStackId(options.activeStackId))
+                return undefined;
+            const parsed = parseResourceSelector(options.activeStackId);
+            if (parsed.ok) {
+                const found = createResourceCatalog([...stacks]).resolveSelector(parsed.selector);
+                if (found)
+                    return found;
+            }
+            // Persisted selection no longer resolves; fall back to the default stack
+            // rather than silently starting with no active stack.
+            return chooseDefaultStack([...stacks]);
+        }
+        return chooseDefaultStack([...stacks]);
+    }
+    publish(next) {
+        this.current = deepFreeze(structuredClone(next));
+        return this.current;
+    }
+    get extensionDiagnostics() {
+        return this.extensionDiagnosticsValue;
+    }
+    set extensionDiagnostics(value) {
+        this.extensionDiagnosticsValue = value;
+    }
+    get extensionPaths() {
+        return this.extensionPathsValue;
+    }
+    set extensionPaths(value) {
+        this.extensionPathsValue = value;
+    }
+    extensionDiagnosticsValue = [];
+    extensionPathsValue = [];
+}
+function stripUndefined(value) {
+    if (Array.isArray(value))
+        return value.map(stripUndefined);
+    if (value && typeof value === "object") {
+        const result = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (item === undefined)
+                continue;
+            result[key] = stripUndefined(item);
+        }
+        return result;
+    }
+    return value;
+}
+function deepFreeze(value) {
+    const freeze = (current) => {
+        if (current === null || typeof current !== "object")
+            return;
+        for (const key of Object.keys(current))
+            freeze(current[key]);
+        Object.freeze(current);
+    };
+    freeze(value);
+    return value;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

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

package/docs/README.md

@@ -14,8 +14,8 @@ Use this page as the documentation map. Each subject has one authoritative home;
 
 - [Web editor](guides/web-editor.md)
 - [Prompt-stack patterns and examples](guides/use-cases.md)
+- [Migrating to 0.5](guides/migrating-to-0.5.md)
 - [Foreground delegation](guides/delegation.md) — experimental; read the security boundary before enabling it.
-- [SillyTavern import](guides/sillytavern-import.md)
 - [Custom macros and slots](guides/custom-macros-and-slots.md)
 - [Prompt and payload debugging](guides/debugging.md)
 
@@ -27,15 +27,18 @@ Use this page as the documentation map. Each subject has one authoritative home;
 - [Configuration](reference/configuration.md)
 - [Implemented feature inventory](reference/features.md)
 - [Public API policy](reference/public-api.md)
-- [Experimental subagent adapter contract](reference/subagent-adapter.md)
+- [Experimental subagent host port contract](reference/subagent-host-port.md)
+- [Experimental UI contribution port contract](reference/ui-contribution-port.md)
 
 ## Development
 
 - [Development setup and verification](development/setup.md)
+- [Architecture and development rules](development/architecture-rules.md)
+- [0.5 architecture plan](design/architecture-0.5.md)
 - [Release process](development/release.md)
 - [Roadmap](development/roadmap.md)
 - [Complexity review](development/complexity-review.md)
 
-## Design archive
+## Architecture and design
 
-[The design archive](design/README.md) records decisions and completed investigations. It is historical context, not current user guidance. Current behavior is documented in the guides and reference pages above.
+[Architecture and design](design/README.md) contains the active 0.5 plan plus historical decisions and investigations. Current released behavior remains documented in the guides and reference pages above.

package/docs/concepts/agent-profiles.md

@@ -55,6 +55,6 @@ Provenance is branch-scoped status metadata, not ownership. Reload, resume, tree
 
 ## Delegation is separate
 
-Ordinary profiles cannot be delegated by default. The trusted project's `.pi/forge/config.json` separately authorizes eligible profile IDs and host-specific backend/timeout choices. Deleting a profile removes its delegation policy so a later same-ID profile cannot inherit authority.
+Ordinary profiles cannot be delegated by default. Delegation authorization is owned by the optional `@zihanw/pi-forge-subagents` package in dedicated files, using canonical `project:<id>` or `global:<id>` keys with per-profile backend/timeout overrides. Bare authorization keys are project-only compatibility aliases regardless of file location. The main package reads no subagent configuration, and deleting a profile does not touch `subagents.json`.
 
 Read the [experimental delegation guide](../guides/delegation.md) before enabling it.

package/docs/concepts/prompt-stacks.md

@@ -33,7 +33,7 @@ A slot renders current Pi data at that position:
 }
 ```
 
-Slots cover conversation history, tools, tool guidance, skills, project context, appended system text, variables, model, date, and working directory. See [macros and slots](../reference/macros-and-slots.md).
+Slots cover conversation history, tools, tool guidance, skills, project context, appended system text, model, date, and working directory. See [macros and slots](../reference/macros-and-slots.md).
 
 ## Compilation order
 
@@ -42,7 +42,7 @@ For each new user turn, pi-forge:
 1. Orders enabled blocks and slots exactly as written.
 2. Builds `system` content and applies the stack's `replace`, `append`, or `prepend` mode.
 3. Inserts synthetic user/assistant messages around the movable `chat-history` slot.
-4. Expands built-in, variable, and trusted custom macros.
+4. Compiles forge-v1 templates over `runtime.*`, `parameters.*`, and `extensions.*`.
 5. Applies the stack's tool policy to Pi and filters skills rendered by pi-forge.
 6. Applies outgoing history/compiled regex rules.
 7. Optionally applies destructive finalize rules when an assistant message completes.
@@ -64,7 +64,7 @@ Use `replace` when the model-visible skill list must be controlled. With `append
 1. Long-lived system rules.
 2. Runtime tools and project context.
 3. Chat history with `includeLastUserMessage: false`.
-4. A final user block containing `{{lastUserMessage}}`.
+4. A final user block containing `{{ runtime.lastUserMessage }}`.
 
 This preserves prior context while presenting the current request once, in an explicit final position. History can also filter summaries and roles, drop previous tool traffic, strip assistant thinking, and limit recent messages or characters. pi-forge repairs dangling tool-call/result pairs after filtering.
 
@@ -83,13 +83,13 @@ Stacks may live in the user-global `~/.pi/forge/prompt-stacks/` or the project `
 - A stack may set `autoActivate: true`; conflicting auto-activation in one scope is invalid and fails closed.
 - `default.json` has no special filename role anymore; missing `autoActivate` yields a migration warning.
 - `/preset use none` records an explicit session opt-out.
-- Active stack and session variables follow Pi's session-tree branch.
+- Active stack selection follows Pi's session-tree branch.
 - Restored branch state takes precedence over fresh-session auto-activation.
 - Project auto-activation candidates take precedence over global ones; an invalid or ambiguous project candidate never falls back to a global stack.
 - An auto-activated agent profile takes precedence over standalone stack autoload.
 
 ## Extensions and transforms
 
-Static, turn, and session variables support nested macros and lazy conditionals. Trusted JavaScript/TypeScript registration modules can add macros and slots without putting executable code in stack JSON. Deterministic regex rules can transform model-bound prompt text or, with an explicit warning, replace finalized assistant transcript text.
+Immutable `parameters` support forge-v1 interpolation and pure filters; tool/slot conditionals use `runtime.tool.*` / `runtime.slot.*` booleans. Trusted JavaScript/TypeScript registration modules can add macros and slots without putting executable code in stack JSON. Deterministic regex rules can transform model-bound prompt text or, with an explicit warning, replace finalized assistant transcript text.
 
 See [custom macros and slots](../guides/custom-macros-and-slots.md), [macro reference](../reference/macros-and-slots.md), and [regex schema](../reference/stack-schema.md#regex-transforms).