@zihanw/pi-forge 0.4.0 → 0.5.0

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,17 @@ 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)
 
 ## 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

@@ -6,7 +6,7 @@ An agent profile is a project-local, schema-versioned preset that references one
 
 ## Schema
 
-Profiles live in `.pi/forge/agent-profiles/*.json`:
+Profiles live in `.pi/forge/agent-profiles/*.json` (project scope) or `~/.pi/forge/agent-profiles/*.json` (global scope). Commands accept `reviewer`, `project:reviewer`, and `global:reviewer`; a project profile shadows a same-ID global profile for unqualified lookups. A profile's `promptStack` reference resolves relative to the profile's own scope: a project profile may reference its own project stack by bare ID or a global stack as `global:<id>`; a global profile may only reference global stacks.
 
 ```json
 {
@@ -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: the trusted project's `.pi/forge/subagents.json` authorizes `project:<id>` profiles and the user-global `~/.pi/forge/subagents.json` authorizes `global:<id>` profiles, with per-profile backend/timeout overrides. 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.
 
@@ -74,17 +74,22 @@ Stacks may use either `allow` or `deny` patterns for each resource. Tool policy
 
 External tool additions are preserved in the baseline restored when a restrictive stack is disabled. See the exact behavior in [stack policy reference](../reference/stack-schema.md#tool-and-skill-policy).
 
+## Scopes and shadowing
+
+Stacks may live in the user-global `~/.pi/forge/prompt-stacks/` or the project `.pi/forge/prompt-stacks/`. A project stack shadows a same-ID global stack for unqualified commands. Selectors are `reviewer`, `project:reviewer`, or `global:reviewer`. Duplicate IDs are errors only within one scope.
+
 ## Activation and session behavior
 
-- `default.json` auto-activates unless its metadata opts out.
-- Another stack may set `autoActivate: true`; conflicting auto-activation is invalid.
+- 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).

package/docs/design/README.md

@@ -1,8 +1,26 @@
-# Design archive
+# Architecture and design
 
 [Documentation](../README.md)
 
-These documents preserve decisions, reviews, spikes, and implementation history. They are not the authoritative description of current user behavior; use the [guides](../README.md#guides) and [reference](../README.md#reference) for that.
+The active plan defines the executable forward-looking work. Archived documents preserve the long-term target, decisions, reviews, spikes, and implementation history; they are not the authoritative description of current user behavior. Use the [guides](../README.md#guides) and [reference](../README.md#reference) for released behavior.
+
+## Active 0.5.0 plan
+
+- [Lean 0.5.0 architecture plan](architecture-0.5.md) — executable breaking-cleanup scope, accepted decisions, implementation lanes, and release gates.
+- [Architecture and development rules](../development/architecture-rules.md) — dependency direction and ownership rules for the full target.
+- [Architecture decision template](decision-template.md) — structure for future boundary/product decisions.
+
+## Archived 0.5 full proposal
+
+The original six-phase target remains the long-term goal and is preserved here:
+
+- [Full proposal index](archive/0.5-full-proposal/README.md)
+- [Full 0.5 architecture plan](archive/0.5-full-proposal/architecture-0.5.md)
+- [Migration inventory](archive/0.5-full-proposal/0.5-inventory.md)
+- [Public-consumer audit](archive/0.5-full-proposal/0.5-consumer-audit.md)
+- [Phase-0 decision drafts](archive/0.5-full-proposal/0.5-phase0-decision-drafts.md)
+- [Template-language spike](archive/0.5-full-proposal/template-language-spike.md)
+- [Pi host-discovery spike](archive/0.5-full-proposal/host-discovery-spike.md)
 
 ## Subagent design history
 
@@ -14,4 +32,4 @@ These documents preserve decisions, reviews, spikes, and implementation history.
 
 - [0.4 roadmap and implementation log](roadmap-0.4-archive.md)
 
-The current exported semantics are in the [subagent adapter contract](../reference/subagent-adapter.md); forward-looking work is in the [roadmap](../development/roadmap.md).
+The 0.5 host boundary is in the [subagent host port contract](../reference/subagent-host-port.md); accepted work ordering is in the [roadmap](../development/roadmap.md).