@josephyoung/pi-file-reference 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Cheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# pi-file-reference
+
+A [pi](https://github.com/earendil-works/pi-coding-agent) extension that resolves `@filepath` references in `AGENTS.md` and injects the referenced file contents into the system prompt.
+
+## How it works
+
+1. On `session_start`, the extension reads `AGENTS.md` (project-local first, then `~/.pi/agent/` as fallback)
+2. Parses `@filepath` references from the file
+3. Reads the referenced files and caches their contents in session state (survives reload)
+4. On `before_agent_start`, injects the file contents into the system prompt
+
+## @filepath syntax
+
+```
+@path/to/file.md
+@./path/to/file.md
+@~/path/to/file.md
+@"path with spaces.md"
+@/absolute/path/to/file.md
+```
+
+The `@` must be at the start of a line or preceded by whitespace.
+
+## Installation
+
+```bash
+# Install from npm (once published)
+pi install pi-file-reference
+
+# Or clone and link locally
+git clone https://github.com/your-org/pi-file-reference.git
+cd pi-file-reference
+npm install
+pi install .
+```
+
+## Usage
+
+In your `AGENTS.md`:
+
+```markdown
+# Project guidelines
+Always follow the patterns in @./docs/style-guide.md
+
+# Architecture
+@~/.project-arch/backend-overview.md
+```
+
+The referenced files' content is automatically injected into the system prompt at the start of each agent turn.
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,174 @@
+import type { ExtensionAPI, CustomEntry } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const AGENTS_FILE = "AGENTS.md";
+const STORE_KEY = "agents-at-context";
+
+/**
+ * Parse @filepath references from a line.
+ *
+ * Rules:
+ * - @ must be preceded by whitespace or start-of-line
+ * - @ followed by a double-quoted string: extract inside quotes
+ * - @ followed by unquoted text: extract until whitespace
+ */
+function parseRefs(line: string): string[] {
+  const refs: string[] = [];
+  let i = 0;
+
+  while (i < line.length) {
+    const atIdx = line.indexOf("@", i);
+    if (atIdx === -1) break;
+
+    // @ must be preceded by start-of-line or whitespace
+    if (atIdx > 0 && line[atIdx - 1] !== " " && line[atIdx - 1] !== "\t") {
+      i = atIdx + 1;
+      continue;
+    }
+
+    i = atIdx + 1;
+    let ref: string;
+
+    if (line[i] === '"') {
+      // Quoted reference: @"path/to/file"
+      const close = line.indexOf('"', i + 1);
+      ref = close === -1 ? line.slice(i + 1) : line.slice(i + 1, close);
+      i = close === -1 ? line.length : close + 1;
+    } else {
+      // Unquoted reference: @path/to/file (until whitespace)
+      const start = i;
+      while (i < line.length && !/\s/.test(line[i])) i++;
+      ref = line.slice(start, i);
+    }
+
+    if (ref) refs.push(ref);
+  }
+
+  return refs;
+}
+
+/**
+ * Resolve a reference path against baseDir.
+ *
+ * Handles:
+ * - Absolute paths (/foo/bar) — used as-is
+ * - Tilde paths (~/foo or ~user/foo) — expanded via os.homedir()
+ * - Relative paths — resolved against baseDir
+ */
+function resolveRef(ref: string, baseDir: string): string {
+  if (ref.startsWith("/")) return ref;
+  if (ref.startsWith("~")) {
+    // ~/path or ~user/path
+    const slashIdx = ref.indexOf("/");
+    if (slashIdx === -1) {
+      // Just ~ or ~user — unlikely, but handle gracefully
+      return path.join(os.homedir(), ref.slice(1));
+    }
+    const userPart = ref.slice(1, slashIdx);
+    if (!userPart) {
+      // ~/path
+      return path.join(os.homedir(), ref.slice(slashIdx + 1));
+    }
+    // ~user/ — tilde expansion for other users; falls back to homedir + user
+    return path.join(os.homedir(), userPart, ref.slice(slashIdx + 1));
+  }
+  return path.resolve(baseDir, ref);
+}
+
+/** A resolved file reference with its content. */
+interface RefContent {
+  ref: string;
+  content: string;
+}
+
+/**
+ * Find and parse AGENTS.md, collect @filepath references.
+ *
+ * Search order:
+ * 1. <cwd>/AGENTS.md
+ * 2. ~/.pi/agent/AGENTS.md
+ */
+function loadRefs(cwd: string): RefContent[] {
+  const candidates = [
+    path.join(cwd, AGENTS_FILE),
+    path.join(os.homedir(), ".pi", "agent", AGENTS_FILE),
+  ];
+
+  let agentsPath: string | undefined;
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      agentsPath = candidate;
+      break;
+    }
+  }
+
+  if (!agentsPath) return [];
+
+  const raw = fs.readFileSync(agentsPath, "utf-8");
+  const baseDir = path.dirname(agentsPath);
+
+  // Collect all refs from all lines
+  const allRefs: string[] = [];
+  for (const line of raw.split("\n")) {
+    allRefs.push(...parseRefs(line));
+  }
+
+  // Deduplicate while preserving order
+  const seen = new Set<string>();
+  const uniqueRefs = allRefs.filter((ref) => {
+    if (seen.has(ref)) return false;
+    seen.add(ref);
+    return true;
+  });
+
+  // Read each referenced file
+  const results: RefContent[] = [];
+  for (const ref of uniqueRefs) {
+    const resolvedPath = resolveRef(ref, baseDir);
+    if (fs.existsSync(resolvedPath)) {
+      results.push({ ref, content: fs.readFileSync(resolvedPath, "utf-8") });
+    } else {
+      console.warn(`[agents-at-reader] @${ref} -> ${resolvedPath} not found, skipping`);
+    }
+  }
+
+  return results;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    // Check if custom entry already exists (e.g., after reload)
+    const entries = ctx.sessionManager.getEntries();
+    const existing = entries.find(
+      (e): e is CustomEntry<{ refs: RefContent[] }> =>
+        e.type === "custom" && e.customType === STORE_KEY,
+    );
+    if (existing) return;
+
+    const refs = loadRefs(ctx.cwd);
+    if (refs.length === 0) return;
+
+    pi.appendEntry(STORE_KEY, { refs });
+  });
+
+  pi.on("before_agent_start", (event, ctx) => {
+    const entries = ctx.sessionManager.getEntries();
+    const entry = entries.find(
+      (e): e is CustomEntry<{ refs: RefContent[] }> =>
+        e.type === "custom" && e.customType === STORE_KEY,
+    );
+    if (!entry?.data?.refs?.length) return;
+
+    const injected = entry.data.refs
+      .map((r) => `// @${r.ref}\n${r.content}`)
+      .join("\n\n");
+
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        `\n\n---\n// @AGENTS.md 引用文件 — 注入以下文件内容供参考\n${injected}\n---`,
+    };
+  });
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@josephyoung/pi-file-reference",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Pi extension that resolves @filepath references in AGENTS.md and injects file content into system prompt",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension"
+  ],
+  "homepage": "https://github.com/josephyoung/pi-file-reference#readme",
+  "bugs": {
+    "url": "https://github.com/josephyoung/pi-file-reference/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josephyoung/pi-file-reference.git"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@types/node": "^25.7.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["agents-at-reader.ts"]
+}