@guuey/fs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+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,132 @@
+# `@guuey/fs`
+
+> Dev-guidance helper for GuueyFS — the per-(app, user, session) filesystem
+> every agent hosted on [guuey.com](https://guuey.com) runs inside. There is
+> no wrapper API: **plain `node:fs` on the three paths below IS the
+> contract.** This package just tells you where they are.
+
+## Install
+
+```sh
+npm install @guuey/fs
+# or
+pnpm add @guuey/fs
+```
+
+## The three paths
+
+Every hosted agent invoke runs with three directories bound in, one per
+layer:
+
+| Helper         | Layer     | Read/write         | Lifetime                                                                     |
+| -------------- | --------- | ------------------ | ---------------------------------------------------------------------------- |
+| `homeDir()`    | `home`    | read-write         | Durable, per (app, user) — survives restarts and new sessions.               |
+| `appDir()`     | `app`     | read-only          | Shared across every user of the app; ships with the app, not per-user.       |
+| `sessionDir()` | `session` | read-write (= cwd) | Scratch for THIS turn's session. Pod-local — does not survive a pod restart. |
+
+```ts
+import { homeDir, appDir, sessionDir } from "@guuey/fs";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+// Durable per-user memory — plain node:fs, nothing else.
+const memoryPath = join(homeDir(), "memories", "MEMORY.md");
+await mkdir(join(homeDir(), "memories"), { recursive: true });
+await writeFile(memoryPath, "User prefers dark mode.\n", { flag: "a" });
+const memory = await readFile(memoryPath, "utf8").catch(() => undefined);
+
+// Shared, read-only per-app assets your build ships with the agent.
+const template = await readFile(join(appDir(), "templates", "welcome.md"), "utf8");
+
+// Scratch space for this session — sessionDir() IS process.cwd(), so plain
+// relative paths already resolve here.
+await writeFile("draft.txt", "working notes for this turn\n");
+// equivalent: join(sessionDir(), "draft.txt")
+```
+
+Each helper throws a clear error if its env var isn't set — that's the
+signal you're not running inside the guuey Router (`guuey dev` or the
+hosted runtime). There's nothing to configure and nothing to catch
+silently: either you're on a guuey pod and the paths are there, or you
+aren't and the helper tells you so immediately.
+
+## Memory behavior — the part that matters
+
+Once the durable filesystem is enabled for an environment (the GuueyFS
+rollout — operator-gated per env, see Status below), this is the target
+contract:
+
+- **Signed-in users**: `homeDir()` is durable cross-session memory. Files an
+  agent writes today are there next week, from a different pod, after a
+  restart.
+- **Guests (anonymous sessions)**: `homeDir()` is still a real, writable
+  directory — but it's backed by pod-local ephemeral scratch, not durable
+  storage. Nothing a guest writes survives past the pod's lifetime. This is
+  a deliberate platform boundary (guests never accumulate durable storage),
+  not a bug — don't build a feature that assumes guest `homeDir()` writes
+  persist.
+- **`sessionDir()`** is pod-local scratch for every caller, guest or
+  signed-in — by contract, not a deferred feature. Don't put anything there
+  you need past the current session.
+
+**Automatic recall is `claude-agent-sdk`-only today.** The three paths above
+— including `homeDir()`'s durable-for-signed-in-users behavior — are the
+same on every framework Guuey hosts. What's framework-scoped is the
+Router's automatic recall: on `claude-agent-sdk`, the platform reads
+`<home>/memories/MEMORY.md` before each turn and injects it into the
+model's context for you, for free. On openai-agents-sdk and google-adk,
+that automatic injection doesn't happen yet — an agent on those frameworks
+can still read/write the same file with plain `node:fs` (as above), it just
+has to do the reading itself. All-framework automatic recall arrives with
+guuey's own memory MCP (a platform tool every framework calls over its
+existing MCP channel). Separately: framework-native memory backends (e.g.
+Google ADK's Vertex MemoryBank) are unsupported on Guuey — they store user
+data outside guuey's deletion boundary, and there's no data-governance
+policy for that yet.
+
+Until the rollout reaches an environment, hosted agents there DO still get
+`GUUEY_HOME_DIR`/`GUUEY_APP_DIR` — pointing at pod-local ephemeral storage.
+Writes to `homeDir()` work, but nothing survives the pod: treat every layer
+as session-lifetime until the durable filesystem is enabled for your
+environment. The helpers' throw only signals you're outside the guuey
+runtime entirely (no `guuey dev`, no hosted pod) — it is not a durability
+signal.
+
+## What this package is NOT
+
+- **Not a storage adapter.** There's no `FsSource`, no versioning/CoW
+  overlay, no read/write resolution logic to import. Base-path injection —
+  the Router hands you three real directories — won that design; a client
+  library on top of it would just be indirection.
+- **Not a durability guarantee by itself.** The env vars are the contract;
+  whether `homeDir()` is backed by durable storage depends on whether the
+  durable filesystem is enabled for the environment AND whether the caller
+  is signed in (see Memory behavior above) — this package can't change
+  that, only report where the paths are.
+
+## Status
+
+🧪 **Developer preview (`0.x`).** The three-path shape (`home`/`app`/
+`session`) and the env-var names (`GUUEY_HOME_DIR`, `GUUEY_APP_DIR`,
+`process.cwd()`) are the actual production contract, not a preview of one —
+code written against this package today keeps working unchanged when the
+durable-filesystem rollout reaches your environment. What exists vs.
+what's coming:
+
+| Piece                                               | Status                                                     |
+| --------------------------------------------------- | ---------------------------------------------------------- |
+| `homeDir()`/`appDir()`/`sessionDir()` helpers       | ✅ shipped                                                 |
+| Env-var contract (`GUUEY_HOME_DIR`/`GUUEY_APP_DIR`) | ✅ shipped                                                 |
+| Durable per-user `home` (signed-in users)           | 🔜 lands with the GuueyFS rollout (operator-gated per env) |
+| Guest `home` = pod-local ephemeral                  | 🔜 lands with the GuueyFS rollout (operator-gated per env) |
+| Per-user/per-app storage quotas                     | 🔜 enforced at the filesystem layer, not visible here      |
+
+Until the rollout reaches an environment, the durable backing is off there
+(`GUUEY_FS_BASE` unset) — but hosted agents still get the env vars, pointing
+at pod-local ephemeral storage: writes work, nothing survives the pod (see
+Memory behavior above).
+
+This package is optional sugar — three one-line env-var reads. You can
+skip it entirely and read `process.env.GUUEY_HOME_DIR` /
+`process.env.GUUEY_APP_DIR` / `process.cwd()` yourself; nothing here is
+magic.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @guuey/fs — a tiny dev-guidance helper for the GuueyFS 3-layer contract every
+ * hosted guuey agent runs inside. `homeDir()`/`appDir()`/`sessionDir()` just read
+ * the env vars the Router already injects (`GUUEY_HOME_DIR`/`GUUEY_APP_DIR`) plus
+ * `process.cwd()` — there is no wrapper API, no adapter, no storage abstraction.
+ * Plain `node:fs` on the three paths IS the contract. See README.md and
+ * docs/superpowers/specs/2026-07-20-guueyfs-slice4-design.md §6.
+ */
+export { ENV_HOME_DIR, ENV_APP_DIR, homeDir, appDir, sessionDir } from "./roots.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @guuey/fs — a tiny dev-guidance helper for the GuueyFS 3-layer contract every
+ * hosted guuey agent runs inside. `homeDir()`/`appDir()`/`sessionDir()` just read
+ * the env vars the Router already injects (`GUUEY_HOME_DIR`/`GUUEY_APP_DIR`) plus
+ * `process.cwd()` — there is no wrapper API, no adapter, no storage abstraction.
+ * Plain `node:fs` on the three paths IS the contract. See README.md and
+ * docs/superpowers/specs/2026-07-20-guueyfs-slice4-design.md §6.
+ */
+export { ENV_HOME_DIR, ENV_APP_DIR, homeDir, appDir, sessionDir } from "./roots.js";

package/dist/roots.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Env-var names the Router injects so agent code reaches the home/app layers
+ * portably. This package's OWN copy (trivial string literals — not imported,
+ * so the published `@guuey/fs` package has zero non-devDependency deps and
+ * cannot depend on the platform-private contract package). Sync sites if
+ * these ever change: `backend/libs/fs-contract/src/contract.ts` (the
+ * platform-internal source of truth) and `oss/packages/host/src/frameworks/
+ * claude-options.ts:41-45` (same OSS-legality constraint, same literals).
+ */
+export declare const ENV_HOME_DIR = "GUUEY_HOME_DIR";
+export declare const ENV_APP_DIR = "GUUEY_APP_DIR";
+/** The user's durable memory layer root (reads GUUEY_HOME_DIR, Router-injected). */
+export declare function homeDir(env?: NodeJS.ProcessEnv): string;
+/** The app's shared read-only layer root (reads GUUEY_APP_DIR, Router-injected). */
+export declare function appDir(env?: NodeJS.ProcessEnv): string;
+/** The per-session working dir = the process cwd (the Router sets cwd = sessionDir). */
+export declare function sessionDir(cwd?: () => string): string;
+//# sourceMappingURL=roots.d.ts.map

package/dist/roots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roots.d.ts","sourceRoot":"","sources":["../src/roots.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAC7C,eAAO,MAAM,WAAW,kBAAkB,CAAC;AAE3C,oFAAoF;AACpF,wBAAgB,OAAO,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEpE;AAED,oFAAoF;AACpF,wBAAgB,MAAM,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEnE;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,MAAoB,GAAG,MAAM,CAElE"}

package/dist/roots.js

@@ -0,0 +1,30 @@
+/**
+ * Env-var names the Router injects so agent code reaches the home/app layers
+ * portably. This package's OWN copy (trivial string literals — not imported,
+ * so the published `@guuey/fs` package has zero non-devDependency deps and
+ * cannot depend on the platform-private contract package). Sync sites if
+ * these ever change: `backend/libs/fs-contract/src/contract.ts` (the
+ * platform-internal source of truth) and `oss/packages/host/src/frameworks/
+ * claude-options.ts:41-45` (same OSS-legality constraint, same literals).
+ */
+export const ENV_HOME_DIR = "GUUEY_HOME_DIR";
+export const ENV_APP_DIR = "GUUEY_APP_DIR";
+/** The user's durable memory layer root (reads GUUEY_HOME_DIR, Router-injected). */
+export function homeDir(env = process.env) {
+    return requireRoot(env, ENV_HOME_DIR);
+}
+/** The app's shared read-only layer root (reads GUUEY_APP_DIR, Router-injected). */
+export function appDir(env = process.env) {
+    return requireRoot(env, ENV_APP_DIR);
+}
+/** The per-session working dir = the process cwd (the Router sets cwd = sessionDir). */
+export function sessionDir(cwd = process.cwd) {
+    return cwd();
+}
+function requireRoot(env, name) {
+    const value = env[name];
+    if (!value) {
+        throw new Error(`${name} is not set — the guuey agent runtime injects it. Run via \`guuey dev\` or the hosted runtime.`);
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@guuey/fs",
+  "version": "0.1.0",
+  "description": "GuueyFS dev-guidance helper — homeDir()/appDir()/sessionDir() read the three env-var/cwd paths the guuey Router injects into every hosted agent. No wrapper API: plain node:fs on the returned paths IS the contract.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "guuey",
+    "filesystem",
+    "vfs",
+    "layers",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withguuey/guuey-sdks.git",
+    "directory": "packages/fs"
+  },
+  "homepage": "https://guuey.com",
+  "bugs": {
+    "url": "https://github.com/loqu-co/guuey/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}