@jals1212/pi-spaces 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@ commands and options and a patch version fixes.
 
 ## Unreleased
 
+## 0.3.0
+
+### Added
+
+- Pi knows the space it runs in. Every Pi with the extension sets
+  `PI_SPACE` (unset in the base home), `PI_SPACE_HOME` (its agent home) and
+  `PI_SPACES_COMMAND` (its configured value, else `pi`), with or without a
+  switch, and the system prompt gets a `<pi_space>` section with the same
+  facts. `spaceInfo`, `exportSpaceInfo` and `spacePrompt` in the core build
+  them.
+- A `pi-spaces` skill, declared in the package, that tells agents what a
+  space is, how to read the current space, home and command, and which
+  `/space` or `pi-space` action to use.
+
+### Changed
+
+- The status line shows the active space as `◆ <name>` instead of
+  `space: <name>`, so it stands out among other extensions' statuses.
+
 ## 0.2.0
 
 ### Added

package/README.md

@@ -65,7 +65,7 @@ A new space starts empty except for a `settings.json` that declares this package
 | `/space remove <name> [--yes] [--no-backup]` | Deletes a space after asking, then asks whether to keep a backup in `<spaces folder>/.backups` (keeping one is first in the list; dismissing the question keeps the space). `--yes` skips the questions and keeps a backup; it is required without a dialog (print and JSON modes). `--no-backup` deletes without one. |
 | `pi --space <name>` | Starts Pi directly in a space, keeping the prompt and every other option. |
 
-The status line shows `space: <name>` while a space is active, and nothing in the base home.
+The status line shows `◆ <name>` while a space is active, and nothing in the base home.
 
 Choosing an argument such as `switch` from the `/space ` suggestions only fills the line; press Enter again to run it. `/space` and Enter opens the picker in one step.
 
@@ -99,6 +99,22 @@ Set for the Pi a switch starts:
 | `PI_SPACE` | The space's name. Unset in the base home. |
 | `PI_SPACES_BASE_HOME` | The home Pi started with, so `base` and the spaces folder survive switches. |
 
+Set in every Pi this extension runs in, even one started without a switch, for its tools and the programs they start:
+
+| Variable | Meaning |
+| --- | --- |
+| `PI_SPACE` | The active space's name, unset in the base home: the same variable a switch sets. |
+| `PI_SPACE_HOME` | The agent home this Pi runs with: the space's folder, or the base home. |
+| `PI_SPACES_COMMAND` | Kept when it has a value; set to `pi` when it is unset or blank. |
+
+### What the model is told
+
+Before each run the system prompt gets a `<pi_space>` section with the same three facts: the space (or the base home), the agent home, and the command, with `<command> --space <name>` and `/space` as the ways to change space. The model knows where it runs without reading the environment. A Pi without structured prompt sections gets no section; the variables are still set.
+
+### The `pi-spaces` skill
+
+The package also ships a `pi-spaces` skill (`skills/pi-spaces/SKILL.md`). It tells agents what a space is, how to read the current space, home and command, and which `/space` or `pi-space` action to use or propose for listing, creating, switching and removing spaces. Pi loads it when a task is about spaces; `/skill:pi-spaces` loads it by hand.
+
 ### Exit status
 
 | Status | `pi --space` |

package/dist/command.js

@@ -157,7 +157,7 @@ function switchTo(name        , deps                  )       {
 /** Status line text: the active space, or nothing in the base home. */
 export function statusText(dir        , currentHome        )                     {
 	const active = activeSpace(dir, currentHome);
-	return active === undefined ? undefined : `space: ${active}`;
+	return active === undefined ? undefined : `◆ ${active}`;
 }
 
 export function completeSpaceArgs(prefix        , dir        )                                            {

package/dist/context.js

@@ -0,0 +1,63 @@
+// What this Pi process knows about its space: the active space, the agent home and the command
+// that starts Pi. It is exported to the environment (for tools and child processes) and told to the model.
+import { resolve } from "node:path";
+import { activeSpace,          } from "./spaces.js";
+
+                            
+	                                                       
+	                          
+	                                        
+	             
+	                                                                  
+	                
+ 
+
+/**
+ * Read once, when the extension loads: Pi keeps its agent home for the whole process, and
+ * the active space cannot be renamed or removed, so the facts hold until Pi exits.
+ */
+export function spaceInfo(dir        , agentHome        , env     )            {
+	return {
+		space: activeSpace(dir, agentHome),
+		home: resolve(agentHome),
+		// A blank value counts as unset, so the default is pi, as in the pi-space command.
+		command: env.PI_SPACES_COMMAND?.trim() || "pi",
+	};
+}
+
+/** Sets PI_SPACE (removed in the base home), PI_SPACE_HOME and PI_SPACES_COMMAND. */
+export function exportSpaceInfo(env     , info           )       {
+	if (info.space === undefined) delete env.PI_SPACE;
+	else env.PI_SPACE = info.space;
+	env.PI_SPACE_HOME = info.home;
+	env.PI_SPACES_COMMAND = info.command;
+}
+
+/** The system prompt section that tells the model where it runs. */
+export function spacePrompt(info           )         {
+	const where = info.space === undefined
+		? "This Pi runs in the base home, outside any space."
+		: `This Pi runs in the space "${info.space}" (PI_SPACE).`;
+	const home = `Agent home: ${info.home} (PI_SPACE_HOME).`;
+	const start = `\`${info.command} --space <name>\` starts it in a space`;
+	const manage = "`/space` lists, creates, removes and switches spaces";
+	const command = `Command that starts Pi: ${info.command} (PI_SPACES_COMMAND); ${start}, and ${manage}.`;
+	return [where, home, command].join("\n");
+}
+
+/** The part of a run's structured prompt options this package writes. */
+                                 
+	                                  
+ 
+
+/**
+ * Sets the <pi_space> section in a run's structured prompt options, creating the section map when
+ * it is missing and replacing an earlier pi_space section. Other sections and the rest of the
+ * prompt are left alone. Without structured options (an older Pi) nothing is added; the
+ * environment still has the facts.
+ */
+export function addSpaceSection(options                            , info           )       {
+	if (options === undefined) return;
+	options.sections ??= {};
+	options.sections.pi_space = spacePrompt(info);
+}

package/extensions/spaces.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { completeSpaceArgs, runSpaceCommand, statusText } from "../src/command.ts";
+import { addSpaceSection, exportSpaceInfo, spaceInfo } from "../src/context.ts";
 import { planStartup, relaunchCommand, runNow, scheduleRelaunch } from "../src/relaunch.ts";
 import { findOwnDeclaration, spacesDir } from "../src/spaces.ts";
 
@@ -20,6 +21,11 @@ export default function (pi: ExtensionAPI) {
 	}
 	if (plan.kind === "relaunch") process.exit(runNow(plan.command, plan.env));
 
+	// Where this Pi runs: exported for tools and the programs they start, and told to the model before each run.
+	const info = spaceInfo(spacesDir(), getAgentDir(), process.env);
+	exportSpaceInfo(process.env, info);
+	pi.on("before_agent_start", (event) => addSpaceSection(event.systemPromptOptions, info));
+
 	pi.registerFlag("space", { description: "Start Pi in this space (see /space list)", type: "string" });
 
 	pi.on("session_start", (_event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/pi-spaces",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Named spaces for Pi: keep several agent homes (sign-ins, packages, settings) and pick one by name.",
   "license": "MIT",
   "author": "jals1212",
@@ -25,12 +25,16 @@
   "pi": {
     "extensions": [
       "./extensions/spaces.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "files": [
     "dist",
     "src",
     "extensions",
+    "skills",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -41,7 +45,10 @@
   "scripts": {
     "build": "node --disable-warning=ExperimentalWarning scripts/build.mjs",
     "prepack": "npm run build",
-    "test": "node scripts/link-self.mjs && npm run build && node --test 'tests/*.test.ts' && npm test --prefix cli"
+    "test": "node scripts/link-self.mjs && npm run build && node --test \"tests/*.test.ts\" && npm test --prefix cli"
+  },
+  "devDependencies": {
+    "cross-spawn": "^7.0.6"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/skills/pi-spaces/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pi-spaces
+description: "Trigger: pi-spaces, space, spaces, /space, pi-space, pi --space, PI_SPACE, PI_SPACE_HOME, PI_SPACES_COMMAND, which space, agent home, base home. Know which Pi space this session runs in, its home and start command, and how spaces are listed, created, switched and removed."
+license: MIT
+metadata:
+  author: jals1212
+  version: "1.0"
+---
+
+## Activation Contract
+
+Use when a task depends on which Pi agent home this session uses (settings, sign-ins, installed packages, sessions), or when the user asks about spaces. A space is a separate Pi agent home kept in a folder of the spaces folder; the base home is the one Pi started with. Pi reads its home once at startup, so one process stays in one space.
+
+## Hard Rules
+
+- Read where you run from the `<pi_space>` system prompt section; in a shell, from `PI_SPACE` (unset in the base home), `PI_SPACE_HOME` (this Pi's agent home) and `PI_SPACES_COMMAND` (the program that starts Pi, default `pi`). Never guess from `~/.pi/agent`.
+- Files of this session's home (`settings.json`, `extensions/`, `sessions/`, installed packages) live under `PI_SPACE_HOME`; `pi install` and settings changes apply to this space only.
+- Never read `auth.json` or other credential files in any home.
+- You cannot move this session to another space. Ask the user to run `/space switch <name>` (interactive terminal only; Pi restarts), or start another Pi with `$PI_SPACES_COMMAND --space <name>`.
+- Never set `PI_CODING_AGENT_DIR` yourself, and never create, rename or delete space folders with file commands; use `/space` or `pi-space`.
+- Removing a space deletes everything in it: only on the user's explicit request, and keep the backup unless they say otherwise.
+
+## Decision Gates
+
+| Need | Action |
+| --- | --- |
+| Which space, home, command | `<pi_space>` section, or `echo "$PI_SPACE|$PI_SPACE_HOME|$PI_SPACES_COMMAND"` |
+| List spaces from a shell | `pi-space list` (optional `@jals1212/pi-spaces-cli`) |
+| Spaces folder | `PI_SPACES_DIR`, else `spaces` next to the base home (`PI_SPACES_BASE_HOME`, else this home) |
+| Create a space | `pi-space --new <name>`, or ask the user for `/space new <name>` |
+| Work in another space | User runs `/space switch <name>`, or `$PI_SPACES_COMMAND --space <name> "<prompt>"` |
+| Remove a space | User request only: `pi-space --remove <name> --yes` keeps a backup in `.backups` |
+
+Names: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters; `base` is reserved for the base home.
+
+## Execution Steps
+
+1. Read the `<pi_space>` section or the three variables before touching any home file.
+2. Pick the action from Decision Gates; prefer telling the user the `/space` command when it needs the interactive terminal.
+3. Report the space and home you acted on.
+
+## Output Contract
+
+State the space (or "base home"), the agent home path, and the command or `/space` action used or proposed.
+
+## References
+
+- `../../README.md` — commands, environment variables and how switching works.

package/src/command.ts

@@ -157,7 +157,7 @@ function switchTo(name: string, deps: SpaceCommandDeps): void {
 /** Status line text: the active space, or nothing in the base home. */
 export function statusText(dir: string, currentHome: string): string | undefined {
 	const active = activeSpace(dir, currentHome);
-	return active === undefined ? undefined : `space: ${active}`;
+	return active === undefined ? undefined : `◆ ${active}`;
 }
 
 export function completeSpaceArgs(prefix: string, dir: string): { value: string; label: string }[] | null {

package/src/context.ts

@@ -0,0 +1,63 @@
+// What this Pi process knows about its space: the active space, the agent home and the command
+// that starts Pi. It is exported to the environment (for tools and child processes) and told to the model.
+import { resolve } from "node:path";
+import { activeSpace, type Env } from "./spaces.ts";
+
+export interface SpaceInfo {
+	/** The active space, or undefined in the base home. */
+	space: string | undefined;
+	/** The agent home this Pi runs with. */
+	home: string;
+	/** PI_SPACES_COMMAND, the program that starts Pi (default pi). */
+	command: string;
+}
+
+/**
+ * Read once, when the extension loads: Pi keeps its agent home for the whole process, and
+ * the active space cannot be renamed or removed, so the facts hold until Pi exits.
+ */
+export function spaceInfo(dir: string, agentHome: string, env: Env): SpaceInfo {
+	return {
+		space: activeSpace(dir, agentHome),
+		home: resolve(agentHome),
+		// A blank value counts as unset, so the default is pi, as in the pi-space command.
+		command: env.PI_SPACES_COMMAND?.trim() || "pi",
+	};
+}
+
+/** Sets PI_SPACE (removed in the base home), PI_SPACE_HOME and PI_SPACES_COMMAND. */
+export function exportSpaceInfo(env: Env, info: SpaceInfo): void {
+	if (info.space === undefined) delete env.PI_SPACE;
+	else env.PI_SPACE = info.space;
+	env.PI_SPACE_HOME = info.home;
+	env.PI_SPACES_COMMAND = info.command;
+}
+
+/** The system prompt section that tells the model where it runs. */
+export function spacePrompt(info: SpaceInfo): string {
+	const where = info.space === undefined
+		? "This Pi runs in the base home, outside any space."
+		: `This Pi runs in the space "${info.space}" (PI_SPACE).`;
+	const home = `Agent home: ${info.home} (PI_SPACE_HOME).`;
+	const start = `\`${info.command} --space <name>\` starts it in a space`;
+	const manage = "`/space` lists, creates, removes and switches spaces";
+	const command = `Command that starts Pi: ${info.command} (PI_SPACES_COMMAND); ${start}, and ${manage}.`;
+	return [where, home, command].join("\n");
+}
+
+/** The part of a run's structured prompt options this package writes. */
+export interface PromptSections {
+	sections?: Record<string, string>;
+}
+
+/**
+ * Sets the <pi_space> section in a run's structured prompt options, creating the section map when
+ * it is missing and replacing an earlier pi_space section. Other sections and the rest of the
+ * prompt are left alone. Without structured options (an older Pi) nothing is added; the
+ * environment still has the facts.
+ */
+export function addSpaceSection(options: PromptSections | undefined, info: SpaceInfo): void {
+	if (options === undefined) return;
+	options.sections ??= {};
+	options.sections.pi_space = spacePrompt(info);
+}