@qilin-agent/working-directory 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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.i18n.yaml

@@ -0,0 +1,46 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/session/working-directory/README.md
+/:
+  en: 06d920cc3955e86b
+  zh: 1bc4afef77054e66
+/qilin-agent-working-directory:
+  en: 62e2be090bdb40b8
+  zh: 61fc03fdaad53ba9
+/qilin-agent-working-directory/summary:
+  en: 594fc1c3e0a4e9e3
+  zh: c84b91ff6fa06972
+/qilin-agent-working-directory/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 9f0336825ccdaacd
+/qilin-agent-working-directory/use-this-package:
+  en: c7ca8dd85f3346de
+  zh: 4a0a9fe72921fa34
+/qilin-agent-working-directory/understand-the-implementation:
+  en: 975818cfd8c8350d
+  zh: 257fab27b8ca363a
+/qilin-agent-working-directory/further-exploration:
+  en: 7889612b1e9c9549
+  zh: 65b74a3d8471ade7
+/qilin-agent-working-directory/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-working-directory/model-experience/working-directory-context:
+  en: 6fcebaf8006123ef
+  zh: 950162891001da33
+/qilin-agent-working-directory/model-experience/working-directory-context/what-the-model-sees:
+  en: 5b8df05c442e0a86
+  zh: a268d162778bf05b
+/qilin-agent-working-directory/model-experience/working-directory-context/token-effect:
+  en: a02a00deaddbccea
+  zh: 5cb96e31c6dd2d14
+/qilin-agent-working-directory/model-experience/working-directory-context/kv-cache-effect:
+  en: f5a095acef81df3b
+  zh: fdd47f253769ad8f
+/qilin-agent-working-directory/known-limitations-and-deferred-work:
+  en: bd51f0d87df5f9c9
+  zh: 9ef187758e47c003
+/qilin-agent-working-directory/known-limitations-and-deferred-work/dev-note:
+  en: 0a1253c6f7b5e8b9
+  zh: 9f56528562c7c914

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+---
+description: "Change one Session’s working directory while existing processes retain theirs. The selected directory survives replay and appears in user context. A missing directory restores the original project when it remains available."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/working-directory
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Change one Session’s working directory while existing processes retain theirs. The selected directory survives replay and appears in user context. A missing directory restores the original project when it remains available.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount alongside `fs`, `sessionProjections`, and `systemPrompt`. `defaultDirectory` selects an absolute fallback for Sessions without an original directory; omission uses the launch directory. See the [configuration catalog](../../../docs/config-catalog.md).
+
+```yaml
+- name: '@qilin-agent/working-directory'
+```
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+The Session projection owns the effective directory and exposes it in Session observations, so cold readers can use it without activating an Agent; the header continues to identify the original project. Changes serialize per Session, validate through the filesystem provider, check cancellation and Agent lifetime, commit an event, and queue a user-context notice. If notice queuing fails after commit, the operation returns the committed directory and logs a warning; the next request or resume still receives the required directory context. Prompt assembly validates the current directory before publishing its context contribution. Existing processes and sandbox grants keep their independent ownership. The [service implementation](src/index.ts) defines the API.
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Session group](../README.md) — durable Session services.
+- [Tool catalog](../../../docs/tool-catalog.md) — the model-facing tool schemas.
+- [Testing](../../../docs/testing.md) — composition and replay verification.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Working directory context
+
+#### What the model sees
+
+The current value is `Current working directory: <JSON-quoted absolute path>.` The contribution is registered as required and literal: it survives disabled or suppressed optional runtime context, its text is never interpolated as prompt variables, and `refreshContext()` re-resolves it at request admission so a change made after assembly still reaches the same request. Each committed change, including automatic recovery, attempts to queue a user-context notice through the ordinary Agent inbox. Cancellation or disposal may discard unadmitted notices; the durable directory remains available to the next request.
+
+#### Token effect
+
+The initial snapshot and changed values add user-context tokens; unchanged snapshots are not repeated.
+
+#### KV Cache effect
+
+Directory transitions append context without replacing the stable system-prompt prefix. A changed directory or recovery creates new context after retained history.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Missing original project** — when the current directory and the original project are both unavailable, prompt assembly rejects every model turn, including chat-only turns. The service does not choose or recreate a repository. Restore the original directory, or use SDK `setWorkingDirectory` (or `ctx.workingDirectory.set`) to select an existing absolute directory before retrying. Existing shells retain their process-local directories.
+
+<a id="dev-note"></a>
+### Dev Note
+
+None.

package/README.zh.md

@@ -0,0 +1,78 @@
+---
+description: "在既有进程保持各自目录的前提下变更单个 Session 的工作目录。所选目录在回放后依然保留，并出现在用户上下文中；目录缺失时，若原始项目仍可用则恢复它。"
+kind: "package-reference"
+---
+
+# @qilin-agent/working-directory
+
+[English](README.md) | 中文
+
+## 概述
+
+在既有进程保持各自目录的前提下变更单个 Session 的工作目录。所选目录在回放后依然保留，并出现在用户上下文中；目录缺失时，若原始项目仍可用则恢复它。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [延伸阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延后工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+与 `fs`、`sessionProjections`、`systemPrompt` 一同挂载。`defaultDirectory` 为没有原始目录的 Session 指定绝对回退路径，省略则使用启动目录。参见[配置目录](../../../docs/config-catalog.zh.md)。
+
+```yaml
+- name: '@qilin-agent/working-directory'
+```
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+Session 投影持有生效目录并在 Session 观察中暴露它，因此冷读无需激活 Agent 即可使用；header 继续标识原始项目。变更按 Session 串行：经文件系统提供者校验、检查取消与 Agent 生命周期、提交事件、并入队一条用户上下文通知。若提交后入队失败，操作仍返回已提交的目录并记录警告；下一次请求或恢复仍会收到所需的目录上下文。提示词组装会在发布其上下文条目之前校验当前目录。既有进程与沙箱授权保持各自归属。[服务实现](src/index.ts)定义了 API。
+
+-----
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [Session 组](../README.zh.md) — 持久 Session 服务。
+- [工具目录](../../../docs/tool-catalog.zh.md) — 面向模型的工具 schema。
+- [测试](../../../docs/testing.zh.md) — 组合与回放验收。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 工作目录上下文
+
+#### 模型看到什么
+
+当前值形如 `Current working directory: <JSON 引号包裹的绝对路径>.`。该贡献以 required 且 literal 方式注册：即使可选运行时上下文被关闭或抑制也仍然保留，其文本不会被当作提示词变量插值，且 `refreshContext()` 会在请求准入时重新解析它，因此装配之后发生的变更同样能在同一次请求内到达模型。每次提交的变更（含自动恢复）都会尝试通过常规 Agent inbox 排入一条用户上下文通知；取消或销毁可能丢弃尚未接纳的通知，但持久目录对下一次请求仍然可用。
+
+#### token 影响
+
+首次快照与变更值会新增用户上下文 token；未变化的快照不会重复。
+
+#### KV Cache 影响
+
+目录切换以追加方式进入上下文，不替换稳定的系统提示前缀；目录变化或恢复会在保留历史之后产生新上下文。
+
+## 已知限制与延后工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **原始项目缺失** —— 当前目录与原始项目都不可用时，提示词组装会拒绝每一次模型回合（包括纯聊天回合）。本服务不会挑选或重建仓库。请先恢复原目录，或通过 SDK `setWorkingDirectory`（或 `ctx.workingDirectory.set`）指定一个存在的绝对目录后重试。既有 shell 仍保有各自的进程内目录。
+
+<a id="dev-note"></a>
+### 开发备注
+
+无。

package/lib/index.js

@@ -0,0 +1,167 @@
+import { isAbsolute } from "node:path";
+import { Service } from "@qilin-agent/kylin";
+import z from "@qilin-agent/schemastery";
+import { z as z$1 } from "zod";
+import { createUserMessage } from "@qilin-agent/llm";
+//#region lib/types/index.js
+/**
+* Session working directories, durable changes, and model context.
+* @module @qilin-agent/working-directory
+*/
+/** One owner for each Session's effective directory and its model-visible changes. */
+var WorkingDirectoryService = class extends Service {
+	static inject = [
+		"fs",
+		"sessionProjections",
+		"systemPrompt"
+	];
+	static Config = z.object({ defaultDirectory: z.string() });
+	/** Absolute deployment fallback for Sessions with no recorded original directory. */
+	defaultDirectory;
+	pending = /* @__PURE__ */ new WeakMap();
+	operations = /* @__PURE__ */ new Set();
+	lifecycle = new AbortController();
+	constructor(ctx, config) {
+		super(ctx, "workingDirectory");
+		const directory = config.defaultDirectory ?? process.cwd();
+		if (!isAbsolute(directory)) throw new Error("working-directory: defaultDirectory must be absolute");
+		this.defaultDirectory = directory;
+		const directorySchema = z$1.string().min(1).refine(isAbsolute).nullable();
+		ctx.sessionProjections.register({
+			key: "workingDirectory",
+			stateVersion: 1,
+			stateSchema: directorySchema,
+			init: (header) => header.cwd ?? null,
+			apply: (state, event) => event.type === "working-directory/change" ? event.data.cwd : state,
+			wire: {
+				viewSchema: directorySchema,
+				view: (state) => state
+			}
+		});
+		ctx.systemPrompt.context({
+			name: "working-directory:current",
+			order: ctx.systemPrompt.getContextOrder("WORKING_DIRECTORY"),
+			required: true,
+			interpolate: false,
+			text: (context) => context.agent === void 0 ? "" : this.contextText(context.agent.session)
+		});
+		ctx.on("system-prompt/assemble", async (_assembly, context, next) => {
+			if (context.agent === void 0) return next();
+			await this.ensure(context.agent, context.signal);
+			const assembly = await next();
+			this.lifecycle.signal.throwIfAborted();
+			const text = this.contextText(context.agent.session);
+			const contribution = assembly.contexts.find((entry) => entry.name === "working-directory:current");
+			if (contribution === void 0) assembly.contexts.unshift({
+				name: "working-directory:current",
+				text,
+				interpolate: false
+			});
+			else {
+				contribution.text = text;
+				contribution.interpolate = false;
+			}
+			return assembly;
+		}, { prepend: true });
+		ctx.effect(() => async () => {
+			this.lifecycle.abort(/* @__PURE__ */ new Error("working-directory service disposed"));
+			await Promise.allSettled(this.operations);
+		});
+	}
+	/**
+	* Read the committed directory without filesystem I/O.
+	* @param session - Session whose directory is requested.
+	* @returns its effective absolute directory.
+	*/
+	get(session) {
+		return this.ctx.sessionProjections.stateOf(session, "workingDirectory") ?? this.defaultDirectory;
+	}
+	/**
+	* Validate the current directory and restore the original project when it disappeared.
+	* @param agent - live or unpublished Agent owning the Session.
+	* @param signal - cancellation for filesystem inspection.
+	* @returns the existing directory; recovery is committed before fulfillment.
+	* A notice failure is warned without reverting the committed state.
+	* @throws when the original project is also unavailable.
+	*/
+	ensure(agent, signal) {
+		return this.serialize(agent, signal, async (control) => {
+			const current = this.get(agent.session);
+			const target = await this.ctx.fs.resolve(current, { signal: control });
+			const info = await this.ctx.fs.stat(target, control);
+			control.throwIfAborted();
+			agent.ctx.fiber.assertActive();
+			if (info?.type === "directory") {
+				if (this.ctx.sessionProjections.stateOf(agent.session, "workingDirectory") === null) agent.session.append("working-directory/change", { cwd: current });
+				return current;
+			}
+			const original = agent.session.header.cwd ?? this.defaultDirectory;
+			const restored = await this.directory(original, original, control);
+			this.commit(agent, restored, true, control);
+			return restored;
+		});
+	}
+	/**
+	* Change one Session's directory without changing existing processes or permissions.
+	* @param agent - live or unpublished Agent owning the Session.
+	* @param path - absolute path or a path relative to its current directory.
+	* @param signal - cancellation before the durable change.
+	* @returns the canonical absolute directory, committed before fulfillment.
+	* A notice failure is warned; the next request still receives the committed directory.
+	* @throws when the requested path is not an existing directory.
+	*/
+	set(agent, path, signal) {
+		return this.serialize(agent, signal, async (control) => {
+			if (path.length === 0) throw new Error("working-directory: cd must not be empty");
+			const directory = await this.directory(path, this.get(agent.session), control);
+			this.commit(agent, directory, false, control);
+			return directory;
+		});
+	}
+	contextText(session) {
+		return `Current working directory: ${JSON.stringify(this.get(session))}.`;
+	}
+	async directory(path, cwd, signal) {
+		const target = await this.ctx.fs.resolve(path, {
+			cwd,
+			signal
+		});
+		const info = await this.ctx.fs.stat(target, signal);
+		signal.throwIfAborted();
+		if (info?.type !== "directory") throw new Error(`working-directory: directory does not exist: ${JSON.stringify(path)}`);
+		return this.ctx.fs.processPath(target);
+	}
+	commit(agent, directory, recovered, signal) {
+		signal.throwIfAborted();
+		agent.ctx.fiber.assertActive();
+		const previous = this.get(agent.session);
+		if (previous === directory) return;
+		agent.session.append("working-directory/change", { cwd: directory });
+		const notice = createUserMessage({
+			content: [{
+				type: "text",
+				text: recovered ? `The working directory ${JSON.stringify(previous)} is unavailable. The working directory is now ${JSON.stringify(directory)}.` : `The working directory changed from ${JSON.stringify(previous)} to ${JSON.stringify(directory)}.`
+			}],
+			source: { kind: "working-directory" }
+		});
+		try {
+			agent.inject(notice);
+		} catch (error) {
+			this.ctx.logger.warn(`working-directory: committed ${JSON.stringify(directory)}, but could not queue its notice: ${String(error)}`);
+		}
+	}
+	serialize(agent, signal, action) {
+		const session = agent.session;
+		const control = signal === void 0 ? this.lifecycle.signal : AbortSignal.any([this.lifecycle.signal, signal]);
+		const settled = (this.pending.get(session) ?? Promise.resolve()).then(() => {
+			control.throwIfAborted();
+			agent.ctx.fiber.assertActive();
+			return action(control);
+		}).finally(() => this.operations.delete(settled));
+		this.operations.add(settled);
+		this.pending.set(session, settled.then(() => {}, () => {}));
+		return settled;
+	}
+};
+//#endregion
+export { WorkingDirectoryService, WorkingDirectoryService as default };

package/lib/types/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Session working directories, durable changes, and model context.
+ * @module @qilin-agent/working-directory
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+import type { Agent } from '@qilin-agent/agent';
+import type { Session } from '@qilin-agent/session';
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        workingDirectory: WorkingDirectoryService;
+    }
+}
+declare module '@qilin-agent/llm' {
+    interface MessageSourceMap {
+        /**
+         * Committed working-directory transition notices.
+         * @persistenceAttribution
+         */
+        'working-directory': {
+            kind: 'working-directory';
+        };
+    }
+}
+declare module '@qilin-agent/session/types' {
+    interface SessionEventMap {
+        /** Effective working directory; the immutable Session header retains the original project. */
+        'working-directory/change': {
+            /** Absolute directory used by subsequent directory-based operations. */
+            cwd: string;
+        };
+    }
+}
+declare module '@qilin-agent/session-projection/types' {
+    interface SessionProjectionMap {
+        /** Recorded current directory for Session observations, or null when none is recorded. */
+        workingDirectory: string | null;
+    }
+    interface SessionProjectionStateMap {
+        /** Last committed working directory, or null before an explicit value exists. */
+        workingDirectory: string | null;
+    }
+}
+/** Deployment default for Sessions without an original project directory. */
+export interface Config {
+    /** Absolute execution-world fallback directory; omitted values use the launch directory. */
+    defaultDirectory?: string;
+}
+/** One owner for each Session's effective directory and its model-visible changes. */
+export declare class WorkingDirectoryService extends Service {
+    static inject: string[];
+    static Config: z<Config>;
+    /** Absolute deployment fallback for Sessions with no recorded original directory. */
+    readonly defaultDirectory: string;
+    private readonly pending;
+    private readonly operations;
+    private readonly lifecycle;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Read the committed directory without filesystem I/O.
+     * @param session - Session whose directory is requested.
+     * @returns its effective absolute directory.
+     */
+    get(session: Session): string;
+    /**
+     * Validate the current directory and restore the original project when it disappeared.
+     * @param agent - live or unpublished Agent owning the Session.
+     * @param signal - cancellation for filesystem inspection.
+     * @returns the existing directory; recovery is committed before fulfillment.
+     * A notice failure is warned without reverting the committed state.
+     * @throws when the original project is also unavailable.
+     */
+    ensure(agent: Agent, signal?: AbortSignal): Promise<string>;
+    /**
+     * Change one Session's directory without changing existing processes or permissions.
+     * @param agent - live or unpublished Agent owning the Session.
+     * @param path - absolute path or a path relative to its current directory.
+     * @param signal - cancellation before the durable change.
+     * @returns the canonical absolute directory, committed before fulfillment.
+     * A notice failure is warned; the next request still receives the committed directory.
+     * @throws when the requested path is not an existing directory.
+     */
+    set(agent: Agent, path: string, signal?: AbortSignal): Promise<string>;
+    private contextText;
+    private directory;
+    private commit;
+    private serialize;
+}
+export default WorkingDirectoryService;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@qilin-agent/working-directory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Session working directories with durable changes and model context",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/session/working-directory"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/fs": "3.1.4",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/session-projection": "3.1.4",
+    "@qilin-agent/system-prompt": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/session": "3.1.4"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/fs": "3.1.4",
+    "@qilin-agent/agent-loop-testkit": "3.1.4",
+    "@qilin-agent/fs-local": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/system-prompt": "3.1.4",
+    "@qilin-agent/session-projection": "3.1.4",
+    "@qilin-agent/tool-working-directory": "3.1.4",
+    "@qilin-agent/tools": "3.1.4"
+  }
 }