@dexto/tools-plan 1.6.0 → 1.6.2

package/dist/errors.cjs

@@ -0,0 +1,126 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var errors_exports = {};
+__export(errors_exports, {
+  PlanError: () => PlanError,
+  PlanErrorCode: () => PlanErrorCode
+});
+module.exports = __toCommonJS(errors_exports);
+var import_core = require("@dexto/core");
+const PlanErrorCode = {
+  /** Plan already exists for session */
+  PLAN_ALREADY_EXISTS: "PLAN_ALREADY_EXISTS",
+  /** Plan not found for session */
+  PLAN_NOT_FOUND: "PLAN_NOT_FOUND",
+  /** Invalid plan content */
+  INVALID_PLAN_CONTENT: "INVALID_PLAN_CONTENT",
+  /** Session ID required */
+  SESSION_ID_REQUIRED: "SESSION_ID_REQUIRED",
+  /** Invalid session ID (path traversal attempt) */
+  INVALID_SESSION_ID: "INVALID_SESSION_ID",
+  /** Checkpoint not found */
+  CHECKPOINT_NOT_FOUND: "CHECKPOINT_NOT_FOUND",
+  /** Storage operation failed */
+  STORAGE_ERROR: "STORAGE_ERROR"
+};
+const PlanError = {
+  /**
+   * Plan already exists for the given session
+   */
+  planAlreadyExists(sessionId) {
+    return new import_core.DextoRuntimeError(
+      PlanErrorCode.PLAN_ALREADY_EXISTS,
+      "plan",
+      import_core.ErrorType.USER,
+      `A plan already exists for session '${sessionId}'. Use plan_update to modify it.`,
+      { sessionId },
+      "Use plan_update to modify the existing plan, or plan_read to view it."
+    );
+  },
+  /**
+   * Plan not found for the given session
+   */
+  planNotFound(sessionId) {
+    return new import_core.DextoRuntimeError(
+      PlanErrorCode.PLAN_NOT_FOUND,
+      "plan",
+      import_core.ErrorType.NOT_FOUND,
+      `No plan found for session '${sessionId}'.`,
+      { sessionId },
+      "Use plan_create to create a new plan for this session."
+    );
+  },
+  /**
+   * Session ID is required for plan operations
+   */
+  sessionIdRequired() {
+    return new import_core.DextoRuntimeError(
+      PlanErrorCode.SESSION_ID_REQUIRED,
+      "plan",
+      import_core.ErrorType.USER,
+      "Session ID is required for plan operations.",
+      {},
+      "Ensure the tool is called within a valid session context."
+    );
+  },
+  /**
+   * Invalid session ID (path traversal attempt)
+   */
+  invalidSessionId(sessionId) {
+    return new import_core.DextoRuntimeError(
+      PlanErrorCode.INVALID_SESSION_ID,
+      "plan",
+      import_core.ErrorType.USER,
+      `Invalid session ID: '${sessionId}' contains invalid path characters.`,
+      { sessionId },
+      'Session IDs must not contain path traversal characters like "..".'
+    );
+  },
+  /**
+   * Checkpoint not found in plan
+   */
+  checkpointNotFound(checkpointId, sessionId) {
+    return new import_core.DextoRuntimeError(
+      PlanErrorCode.CHECKPOINT_NOT_FOUND,
+      "plan",
+      import_core.ErrorType.NOT_FOUND,
+      `Checkpoint '${checkpointId}' not found in plan for session '${sessionId}'.`,
+      { checkpointId, sessionId },
+      "Use plan_read to view available checkpoints."
+    );
+  },
+  /**
+   * Storage operation failed
+   */
+  storageError(operation, sessionId, cause) {
+    return new import_core.DextoRuntimeError(
+      PlanErrorCode.STORAGE_ERROR,
+      "plan",
+      import_core.ErrorType.SYSTEM,
+      `Failed to ${operation} plan for session '${sessionId}': ${cause?.message || "unknown error"}`,
+      { operation, sessionId, cause: cause?.message },
+      "Check file system permissions and try again."
+    );
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PlanError,
+  PlanErrorCode
+});

package/dist/errors.js

@@ -1,66 +1,101 @@
-/**
- * Plan Error Factory
- *
- * Provides typed errors for plan operations following the DextoRuntimeError pattern.
- */
-import { DextoRuntimeError, ErrorType } from '@dexto/core';
-/**
- * Error codes for plan operations
- */
-export const PlanErrorCode = {
-    /** Plan already exists for session */
-    PLAN_ALREADY_EXISTS: 'PLAN_ALREADY_EXISTS',
-    /** Plan not found for session */
-    PLAN_NOT_FOUND: 'PLAN_NOT_FOUND',
-    /** Invalid plan content */
-    INVALID_PLAN_CONTENT: 'INVALID_PLAN_CONTENT',
-    /** Session ID required */
-    SESSION_ID_REQUIRED: 'SESSION_ID_REQUIRED',
-    /** Invalid session ID (path traversal attempt) */
-    INVALID_SESSION_ID: 'INVALID_SESSION_ID',
-    /** Checkpoint not found */
-    CHECKPOINT_NOT_FOUND: 'CHECKPOINT_NOT_FOUND',
-    /** Storage operation failed */
-    STORAGE_ERROR: 'STORAGE_ERROR',
+import { DextoRuntimeError, ErrorType } from "@dexto/core";
+const PlanErrorCode = {
+  /** Plan already exists for session */
+  PLAN_ALREADY_EXISTS: "PLAN_ALREADY_EXISTS",
+  /** Plan not found for session */
+  PLAN_NOT_FOUND: "PLAN_NOT_FOUND",
+  /** Invalid plan content */
+  INVALID_PLAN_CONTENT: "INVALID_PLAN_CONTENT",
+  /** Session ID required */
+  SESSION_ID_REQUIRED: "SESSION_ID_REQUIRED",
+  /** Invalid session ID (path traversal attempt) */
+  INVALID_SESSION_ID: "INVALID_SESSION_ID",
+  /** Checkpoint not found */
+  CHECKPOINT_NOT_FOUND: "CHECKPOINT_NOT_FOUND",
+  /** Storage operation failed */
+  STORAGE_ERROR: "STORAGE_ERROR"
 };
-/**
- * Error factory for plan operations
- */
-export const PlanError = {
-    /**
-     * Plan already exists for the given session
-     */
-    planAlreadyExists(sessionId) {
-        return new DextoRuntimeError(PlanErrorCode.PLAN_ALREADY_EXISTS, 'plan', ErrorType.USER, `A plan already exists for session '${sessionId}'. Use plan_update to modify it.`, { sessionId }, 'Use plan_update to modify the existing plan, or plan_read to view it.');
-    },
-    /**
-     * Plan not found for the given session
-     */
-    planNotFound(sessionId) {
-        return new DextoRuntimeError(PlanErrorCode.PLAN_NOT_FOUND, 'plan', ErrorType.NOT_FOUND, `No plan found for session '${sessionId}'.`, { sessionId }, 'Use plan_create to create a new plan for this session.');
-    },
-    /**
-     * Session ID is required for plan operations
-     */
-    sessionIdRequired() {
-        return new DextoRuntimeError(PlanErrorCode.SESSION_ID_REQUIRED, 'plan', ErrorType.USER, 'Session ID is required for plan operations.', {}, 'Ensure the tool is called within a valid session context.');
-    },
-    /**
-     * Invalid session ID (path traversal attempt)
-     */
-    invalidSessionId(sessionId) {
-        return new DextoRuntimeError(PlanErrorCode.INVALID_SESSION_ID, 'plan', ErrorType.USER, `Invalid session ID: '${sessionId}' contains invalid path characters.`, { sessionId }, 'Session IDs must not contain path traversal characters like "..".');
-    },
-    /**
-     * Checkpoint not found in plan
-     */
-    checkpointNotFound(checkpointId, sessionId) {
-        return new DextoRuntimeError(PlanErrorCode.CHECKPOINT_NOT_FOUND, 'plan', ErrorType.NOT_FOUND, `Checkpoint '${checkpointId}' not found in plan for session '${sessionId}'.`, { checkpointId, sessionId }, 'Use plan_read to view available checkpoints.');
-    },
-    /**
-     * Storage operation failed
-     */
-    storageError(operation, sessionId, cause) {
-        return new DextoRuntimeError(PlanErrorCode.STORAGE_ERROR, 'plan', ErrorType.SYSTEM, `Failed to ${operation} plan for session '${sessionId}': ${cause?.message || 'unknown error'}`, { operation, sessionId, cause: cause?.message }, 'Check file system permissions and try again.');
-    },
+const PlanError = {
+  /**
+   * Plan already exists for the given session
+   */
+  planAlreadyExists(sessionId) {
+    return new DextoRuntimeError(
+      PlanErrorCode.PLAN_ALREADY_EXISTS,
+      "plan",
+      ErrorType.USER,
+      `A plan already exists for session '${sessionId}'. Use plan_update to modify it.`,
+      { sessionId },
+      "Use plan_update to modify the existing plan, or plan_read to view it."
+    );
+  },
+  /**
+   * Plan not found for the given session
+   */
+  planNotFound(sessionId) {
+    return new DextoRuntimeError(
+      PlanErrorCode.PLAN_NOT_FOUND,
+      "plan",
+      ErrorType.NOT_FOUND,
+      `No plan found for session '${sessionId}'.`,
+      { sessionId },
+      "Use plan_create to create a new plan for this session."
+    );
+  },
+  /**
+   * Session ID is required for plan operations
+   */
+  sessionIdRequired() {
+    return new DextoRuntimeError(
+      PlanErrorCode.SESSION_ID_REQUIRED,
+      "plan",
+      ErrorType.USER,
+      "Session ID is required for plan operations.",
+      {},
+      "Ensure the tool is called within a valid session context."
+    );
+  },
+  /**
+   * Invalid session ID (path traversal attempt)
+   */
+  invalidSessionId(sessionId) {
+    return new DextoRuntimeError(
+      PlanErrorCode.INVALID_SESSION_ID,
+      "plan",
+      ErrorType.USER,
+      `Invalid session ID: '${sessionId}' contains invalid path characters.`,
+      { sessionId },
+      'Session IDs must not contain path traversal characters like "..".'
+    );
+  },
+  /**
+   * Checkpoint not found in plan
+   */
+  checkpointNotFound(checkpointId, sessionId) {
+    return new DextoRuntimeError(
+      PlanErrorCode.CHECKPOINT_NOT_FOUND,
+      "plan",
+      ErrorType.NOT_FOUND,
+      `Checkpoint '${checkpointId}' not found in plan for session '${sessionId}'.`,
+      { checkpointId, sessionId },
+      "Use plan_read to view available checkpoints."
+    );
+  },
+  /**
+   * Storage operation failed
+   */
+  storageError(operation, sessionId, cause) {
+    return new DextoRuntimeError(
+      PlanErrorCode.STORAGE_ERROR,
+      "plan",
+      ErrorType.SYSTEM,
+      `Failed to ${operation} plan for session '${sessionId}': ${cause?.message || "unknown error"}`,
+      { operation, sessionId, cause: cause?.message },
+      "Check file system permissions and try again."
+    );
+  }
+};
+export {
+  PlanError,
+  PlanErrorCode
 };

package/dist/index.cjs

@@ -0,0 +1,36 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+__export(index_exports, {
+  PlanError: () => import_errors.PlanError,
+  PlanErrorCode: () => import_errors.PlanErrorCode,
+  PlanService: () => import_plan_service.PlanService,
+  planToolsFactory: () => import_tool_factory.planToolsFactory
+});
+module.exports = __toCommonJS(index_exports);
+var import_tool_factory = require("./tool-factory.js");
+var import_plan_service = require("./plan-service.js");
+var import_errors = require("./errors.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PlanError,
+  PlanErrorCode,
+  PlanService,
+  planToolsFactory
+});

package/dist/index.d.cts

@@ -0,0 +1,224 @@
+import { ToolFactory } from '@dexto/agent-config';
+import { z } from 'zod';
+import { Logger, DextoRuntimeError } from '@dexto/core';
+
+/**
+ * Plan Tools Factory
+ *
+ * Provides implementation planning tools:
+ * - plan_create: Create a new plan for the session
+ * - plan_read: Read the current plan
+ * - plan_update: Update the existing plan
+ * - plan_review: Request user review of the plan (shows plan content with approval options)
+ */
+
+/**
+ * Configuration schema for Plan tools factory
+ */
+declare const PlanToolsConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"plan-tools">;
+    basePath: z.ZodDefault<z.ZodString>;
+    enabledTools: z.ZodOptional<z.ZodArray<z.ZodEnum<["plan_create", "plan_read", "plan_update", "plan_review"]>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    type: "plan-tools";
+    basePath: string;
+    enabledTools?: ("plan_create" | "plan_read" | "plan_update" | "plan_review")[] | undefined;
+}, {
+    type: "plan-tools";
+    basePath?: string | undefined;
+    enabledTools?: ("plan_create" | "plan_read" | "plan_update" | "plan_review")[] | undefined;
+}>;
+type PlanToolsConfig = z.output<typeof PlanToolsConfigSchema>;
+
+declare const planToolsFactory: ToolFactory<PlanToolsConfig>;
+
+/**
+ * Plan Types and Schemas
+ *
+ * Defines the structure of plans and their metadata.
+ */
+
+/**
+ * Plan status values
+ */
+declare const PlanStatusSchema: z.ZodEnum<["draft", "approved", "in_progress", "completed", "abandoned"]>;
+type PlanStatus = z.infer<typeof PlanStatusSchema>;
+/**
+ * Plan metadata stored alongside the plan content
+ */
+declare const PlanMetaSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<["draft", "approved", "in_progress", "completed", "abandoned"]>>;
+    title: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    status: "draft" | "approved" | "in_progress" | "completed" | "abandoned";
+    sessionId: string;
+    createdAt: number;
+    updatedAt: number;
+    title?: string | undefined;
+}, {
+    sessionId: string;
+    createdAt: number;
+    updatedAt: number;
+    status?: "draft" | "approved" | "in_progress" | "completed" | "abandoned" | undefined;
+    title?: string | undefined;
+}>;
+type PlanMeta = z.infer<typeof PlanMetaSchema>;
+/**
+ * Complete plan with content and metadata
+ */
+interface Plan {
+    content: string;
+    meta: PlanMeta;
+}
+/**
+ * Options for the plan service
+ */
+interface PlanServiceOptions {
+    /** Base directory for plan storage */
+    basePath: string;
+}
+/**
+ * Result of a plan update operation
+ */
+interface PlanUpdateResult {
+    oldContent: string;
+    newContent: string;
+    meta: PlanMeta;
+}
+
+/**
+ * Plan Service
+ *
+ * Handles storage and retrieval of implementation plans.
+ * Plans are stored in .dexto/plans/{sessionId}/ with:
+ * - plan.md: The plan content
+ * - plan-meta.json: Metadata (status, checkpoints, timestamps)
+ */
+
+/**
+ * Service for managing implementation plans.
+ */
+declare class PlanService {
+    private basePath;
+    private logger;
+    constructor(options: PlanServiceOptions, logger: Logger);
+    /**
+     * Resolves and validates a session directory path.
+     * Prevents path traversal attacks by ensuring the resolved path stays within basePath.
+     */
+    private resolveSessionDir;
+    /**
+     * Gets the directory path for a session's plan
+     */
+    private getPlanDir;
+    /**
+     * Gets the path to the plan content file.
+     * Public accessor for tools that need to display the path.
+     */
+    getPlanPath(sessionId: string): string;
+    /**
+     * Gets the path to the plan metadata file
+     */
+    private getMetaPath;
+    /**
+     * Checks if a plan exists for the given session
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Creates a new plan for the session
+     *
+     * @throws PlanError.planAlreadyExists if plan already exists
+     * @throws PlanError.storageError on filesystem errors
+     */
+    create(sessionId: string, content: string, options?: {
+        title?: string;
+    }): Promise<Plan>;
+    /**
+     * Reads the plan for the given session
+     *
+     * @returns The plan or null if not found
+     */
+    read(sessionId: string): Promise<Plan | null>;
+    /**
+     * Updates the plan content for the given session
+     *
+     * @throws PlanError.planNotFound if plan doesn't exist
+     * @throws PlanError.storageError on filesystem errors
+     */
+    update(sessionId: string, content: string): Promise<PlanUpdateResult>;
+    /**
+     * Updates the plan metadata (status, title)
+     *
+     * @throws PlanError.planNotFound if plan doesn't exist
+     * @throws PlanError.storageError on filesystem errors
+     */
+    updateMeta(sessionId: string, updates: Partial<Pick<PlanMeta, 'status' | 'title'>>): Promise<PlanMeta>;
+    /**
+     * Deletes the plan for the given session
+     *
+     * @throws PlanError.planNotFound if plan doesn't exist
+     * @throws PlanError.storageError on filesystem errors
+     */
+    delete(sessionId: string): Promise<void>;
+}
+
+/**
+ * Plan Error Factory
+ *
+ * Provides typed errors for plan operations following the DextoRuntimeError pattern.
+ */
+
+/**
+ * Error codes for plan operations
+ */
+declare const PlanErrorCode: {
+    /** Plan already exists for session */
+    readonly PLAN_ALREADY_EXISTS: "PLAN_ALREADY_EXISTS";
+    /** Plan not found for session */
+    readonly PLAN_NOT_FOUND: "PLAN_NOT_FOUND";
+    /** Invalid plan content */
+    readonly INVALID_PLAN_CONTENT: "INVALID_PLAN_CONTENT";
+    /** Session ID required */
+    readonly SESSION_ID_REQUIRED: "SESSION_ID_REQUIRED";
+    /** Invalid session ID (path traversal attempt) */
+    readonly INVALID_SESSION_ID: "INVALID_SESSION_ID";
+    /** Checkpoint not found */
+    readonly CHECKPOINT_NOT_FOUND: "CHECKPOINT_NOT_FOUND";
+    /** Storage operation failed */
+    readonly STORAGE_ERROR: "STORAGE_ERROR";
+};
+type PlanErrorCodeType = (typeof PlanErrorCode)[keyof typeof PlanErrorCode];
+/**
+ * Error factory for plan operations
+ */
+declare const PlanError: {
+    /**
+     * Plan already exists for the given session
+     */
+    planAlreadyExists(sessionId: string): DextoRuntimeError;
+    /**
+     * Plan not found for the given session
+     */
+    planNotFound(sessionId: string): DextoRuntimeError;
+    /**
+     * Session ID is required for plan operations
+     */
+    sessionIdRequired(): DextoRuntimeError;
+    /**
+     * Invalid session ID (path traversal attempt)
+     */
+    invalidSessionId(sessionId: string): DextoRuntimeError;
+    /**
+     * Checkpoint not found in plan
+     */
+    checkpointNotFound(checkpointId: string, sessionId: string): DextoRuntimeError;
+    /**
+     * Storage operation failed
+     */
+    storageError(operation: string, sessionId: string, cause?: Error): DextoRuntimeError;
+};
+
+export { type Plan, PlanError, PlanErrorCode, type PlanErrorCodeType, type PlanMeta, PlanService, type PlanServiceOptions, type PlanStatus, type PlanUpdateResult, planToolsFactory };

package/dist/index.js

@@ -1,12 +1,9 @@
-/**
- * @dexto/tools-plan
- *
- * Implementation planning tools with session-linked plans.
- * Provides tools for creating, reading, updating, and tracking plans.
- */
-// Tool factory (image-compatible)
-export { planToolsFactory } from './tool-factory.js';
-// Service (for advanced use cases)
-export { PlanService } from './plan-service.js';
-// Error utilities
-export { PlanError, PlanErrorCode } from './errors.js';
+import { planToolsFactory } from "./tool-factory.js";
+import { PlanService } from "./plan-service.js";
+import { PlanError, PlanErrorCode } from "./errors.js";
+export {
+  PlanError,
+  PlanErrorCode,
+  PlanService,
+  planToolsFactory
+};

package/dist/plan-service-getter.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var plan_service_getter_exports = {};
+module.exports = __toCommonJS(plan_service_getter_exports);

package/dist/plan-service-getter.js

@@ -1 +0,0 @@
-export {};