@pencil-agent/nano-pencil 2.0.0-beta.0 → 2.0.0-beta.2

package/dist/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "2.0.0-beta.0",
-  "commitHash": "5ad87db",
+  "version": "2.0.0-beta.2",
+  "commitHash": "4afe936",
   "branch": "refactor/arch-candidate-d",
-  "builtAt": "2026-06-05T10:02:01.628Z"
+  "builtAt": "2026-06-05T15:33:54.463Z"
 }

package/dist/packages/extension-sdk/src/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * [WHO]: Barrel for @pencil-agent/extension-sdk — the stable protocol surface for extensions
+ * [FROM]: Re-exports the per-protocol modules (tools + lifecycle today; themes/hooks/commands/permissions in later P3 checkpoints)
+ * [TO]: Consumed by third-party extensions, packages/mem-core, packages/soul-core, and the host (adopting these contracts)
+ * [HERE]: packages/extension-sdk/src/index.ts - extension-sdk public entry
+ *
+ * Scope (this round / P3): tools (S1), lifecycle (ExtensionAPI/ExtensionContext/SessionManagerContract, S3),
+ * then themes/hooks/commands/permissions. Explicitly NOT here (EVOLUTION-RESERVED): agent-profile,
+ * host-adapter, tool-runtime, a2a-bridge, memory/soul providers — see evolution/PARP.md.
+ */
+export * from "./tools.js";
+export * from "./lifecycle.js";

package/dist/packages/extension-sdk/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * [WHO]: Barrel for @pencil-agent/extension-sdk — the stable protocol surface for extensions
+ * [FROM]: Re-exports the per-protocol modules (tools + lifecycle today; themes/hooks/commands/permissions in later P3 checkpoints)
+ * [TO]: Consumed by third-party extensions, packages/mem-core, packages/soul-core, and the host (adopting these contracts)
+ * [HERE]: packages/extension-sdk/src/index.ts - extension-sdk public entry
+ *
+ * Scope (this round / P3): tools (S1), lifecycle (ExtensionAPI/ExtensionContext/SessionManagerContract, S3),
+ * then themes/hooks/commands/permissions. Explicitly NOT here (EVOLUTION-RESERVED): agent-profile,
+ * host-adapter, tool-runtime, a2a-bridge, memory/soul providers — see evolution/PARP.md.
+ */
+export * from "./tools.js";
+export * from "./lifecycle.js";

package/dist/packages/extension-sdk/src/lifecycle.d.ts

@@ -0,0 +1,73 @@
+/**
+ * [WHO]: Provides ExtensionAPI, ExtensionContext, ExtensionFactory, ExtensionUi, ExtensionCommand,
+ *        SessionManagerContract, HookEventName, HookHandler — the extension lifecycle protocol
+ * [FROM]: No dependencies — minimal structural protocol owned by extension-sdk (S3 dependency-inversion target)
+ * [TO]: Consumed by packages/mem-core (extension adapter) and third-party extensions; the host's
+ *       richer ExtensionContext/ExtensionAPI satisfy these structurally (extensions load dynamically)
+ * [HERE]: packages/extension-sdk/src/lifecycle.ts - the stable extension entry contract
+ *
+ * Scope note: event payloads are intentionally loose (HookHandler's event is `unknown`) this round;
+ * per-event typed payloads land in hooks.ts during P3.1. This file carries only the surface that
+ * lets a host-agnostic extension (e.g. mem-core) compile against the SDK instead of the host package.
+ */
+import type { TSchema } from "@sinclair/typebox";
+import type { ToolContract } from "./tools.js";
+/** Read-only session info an extension may consult via `ctx.sessionManager`. */
+export interface SessionManagerContract {
+    /** Absolute path to the active session's JSONL file, if any. */
+    getSessionFile(): string | undefined;
+    /** Count sessions under `cwd` whose file mtime is newer than `sinceMs`. */
+    countTouchedSince(cwd: string, sinceMs: number, options?: {
+        sessionDir?: string;
+        excludeBasename?: string;
+        concurrency?: number;
+    }): Promise<number>;
+}
+/** UI affordances available to an extension (no-ops / undefined-safe when `hasUI` is false). */
+export interface ExtensionUi {
+    /** Surface a transient message to the user. */
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+    /** Set (or clear with `undefined`) a keyed status line owned by this extension. */
+    setStatus(key: string, text: string | undefined): void;
+}
+/** Runtime context handed to extension hooks, commands, and tools. */
+export interface ExtensionContext {
+    /** Current working directory. */
+    cwd: string;
+    /** Whether an interactive UI is attached (false in print/RPC mode). */
+    hasUI: boolean;
+    /** Read-only session manager. */
+    sessionManager: SessionManagerContract;
+    /** User-facing UI affordances. */
+    ui: ExtensionUi;
+}
+/** Lifecycle hook names an extension may subscribe to via `api.on(...)`. */
+export type HookEventName = "session_start" | "session_ready" | "session_shutdown" | "before_agent_start" | "agent_start" | "agent_end" | "agent_result" | "turn_start" | "turn_end" | "tool_execution_start" | "tool_execution_end";
+/**
+ * Hook callback. The event payload is intentionally `any` this round so host-agnostic
+ * extensions compile without per-event payload types; typed payloads land in hooks.ts (P3.1).
+ */
+export type HookHandler = (event: any, ctx: ExtensionContext) => void | Promise<void>;
+/** A slash command an extension registers via `api.registerCommand(...)`. */
+export interface ExtensionCommand {
+    /** Help text shown in command lists. */
+    description?: string;
+    /** Optional argument-completion provider. */
+    getArgumentCompletions?: (argumentPrefix: string) => Array<{
+        value: string;
+        label: string;
+    }> | null;
+    /** Command body. `args` is the raw argument string (may be empty/undefined). */
+    handler: (args: string | undefined, ctx: ExtensionContext) => void | Promise<void>;
+}
+/** The registration surface a host passes to an extension factory. */
+export interface ExtensionAPI {
+    /** Subscribe to a lifecycle hook. */
+    on(event: HookEventName, handler: HookHandler): void;
+    /** Register a slash command. */
+    registerCommand(name: string, command: ExtensionCommand): void;
+    /** Register a model-facing tool. Generic so each call infers its own parameter schema. */
+    registerTool<TParams extends TSchema = TSchema, TDetails = unknown>(tool: ToolContract<TParams, TDetails>): void;
+}
+/** An extension's default export: receives the host API and wires up hooks/commands/tools. */
+export type ExtensionFactory = (api: ExtensionAPI) => void;

package/dist/packages/extension-sdk/src/lifecycle.js

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: Provides ExtensionAPI, ExtensionContext, ExtensionFactory, ExtensionUi, ExtensionCommand,
+ *        SessionManagerContract, HookEventName, HookHandler — the extension lifecycle protocol
+ * [FROM]: No dependencies — minimal structural protocol owned by extension-sdk (S3 dependency-inversion target)
+ * [TO]: Consumed by packages/mem-core (extension adapter) and third-party extensions; the host's
+ *       richer ExtensionContext/ExtensionAPI satisfy these structurally (extensions load dynamically)
+ * [HERE]: packages/extension-sdk/src/lifecycle.ts - the stable extension entry contract
+ *
+ * Scope note: event payloads are intentionally loose (HookHandler's event is `unknown`) this round;
+ * per-event typed payloads land in hooks.ts during P3.1. This file carries only the surface that
+ * lets a host-agnostic extension (e.g. mem-core) compile against the SDK instead of the host package.
+ */
+export {};

package/dist/packages/extension-sdk/src/tools.d.ts

@@ -0,0 +1,77 @@
+/**
+ * [WHO]: Provides ToolRuntime, ToolPermissions, ToolRuntimeDescriptor (S1 seam) + ToolResult, ToolContract
+ * [FROM]: Depends on @sinclair/typebox (schema) and ./lifecycle (ExtensionContext, type-only)
+ * [TO]: Consumed by the host ToolDefinition (adopts the S1 fields) and by extensions registering tools
+ * [HERE]: packages/extension-sdk/src/tools.ts - tool runtime seam (S1) + the stable tool contract
+ *
+ * S1 seam (refactor-plan §接缝预留): a tool may optionally declare its execution runtime and
+ * permission needs. Omitting both keeps today's behavior (local, host-policy). The host
+ * ToolOrchestrator stays the single dispatch point; browser/remote/mcp runtimes are NOT
+ * implemented this round — only the contract shape is reserved so adding them is additive.
+ */
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { ExtensionContext } from "./lifecycle.js";
+/** Where a tool's execute() runs. Omitted ⇒ "local" (in the host process). */
+export type ToolRuntime = "local" | "mcp" | "remote" | "browser";
+/** Declarative permission requirements a tool may request; the host decides enforcement. */
+export interface ToolPermissions {
+    /** Filesystem paths the tool intends to read / write, if constrained. */
+    filesystem?: {
+        read?: string[];
+        write?: string[];
+    };
+    /** Whether the tool may spawn shell/processes. */
+    process?: boolean;
+    /** Network hosts the tool may reach, if constrained. */
+    network?: string[];
+}
+/** S1 seam: optional runtime/permission descriptors a tool definition may carry. */
+export interface ToolRuntimeDescriptor {
+    /** Execution runtime. Omitted ⇒ "local". */
+    runtime?: ToolRuntime;
+    /** Declared permissions. Omitted ⇒ unconstrained (host policy applies). */
+    permissions?: ToolPermissions;
+}
+/** A single content block a tool returns. */
+export type ToolResultContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType?: string;
+};
+/** The result of executing a tool. */
+export interface ToolResult<TDetails = unknown> {
+    /** Model-facing content blocks. */
+    content: ToolResultContent[];
+    /** Structured details for custom rendering / downstream use. */
+    details?: TDetails;
+    /** Whether this result represents an error. */
+    isError?: boolean;
+}
+/** Callback a tool may invoke to stream partial progress. */
+export type ToolUpdateCallback<TDetails = unknown> = (details: TDetails) => void;
+/**
+ * The stable tool contract an extension registers. The host's richer ToolDefinition is a
+ * superset (adds renderCall/renderResult and tighter agent-core result types); a contract
+ * authored against this interface remains valid there because extensions load dynamically.
+ */
+export interface ToolContract<TParams extends TSchema = TSchema, TDetails = unknown> extends ToolRuntimeDescriptor {
+    /** Tool name used in LLM tool calls. */
+    name: string;
+    /** Human-readable label for UI. */
+    label?: string;
+    /** Description for the model. */
+    description: string;
+    /** Parameter schema (TypeBox). */
+    parameters: TParams;
+    /** Alternative model-facing names accepted for compatibility. */
+    aliases?: string[];
+    /** Whether the tool can safely run alongside other concurrency-safe tools. */
+    isConcurrencySafe?: boolean;
+    /** Optional usage guidance injected into the system prompt. */
+    guidance?: string;
+    /** Execute the tool. Trailing parameters are optional for simple tools. */
+    execute(toolCallId: string, params: Static<TParams>, signal?: AbortSignal, onUpdate?: ToolUpdateCallback<TDetails>, ctx?: ExtensionContext): Promise<ToolResult<TDetails>>;
+}

package/dist/packages/extension-sdk/src/tools.js

@@ -0,0 +1,12 @@
+/**
+ * [WHO]: Provides ToolRuntime, ToolPermissions, ToolRuntimeDescriptor (S1 seam) + ToolResult, ToolContract
+ * [FROM]: Depends on @sinclair/typebox (schema) and ./lifecycle (ExtensionContext, type-only)
+ * [TO]: Consumed by the host ToolDefinition (adopts the S1 fields) and by extensions registering tools
+ * [HERE]: packages/extension-sdk/src/tools.ts - tool runtime seam (S1) + the stable tool contract
+ *
+ * S1 seam (refactor-plan §接缝预留): a tool may optionally declare its execution runtime and
+ * permission needs. Omitting both keeps today's behavior (local, host-policy). The host
+ * ToolOrchestrator stays the single dispatch point; browser/remote/mcp runtimes are NOT
+ * implemented this round — only the contract shape is reserved so adding them is additive.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pencil-agent/nano-pencil",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0-beta.2",
   "description": "CLI writing agent with read, bash, edit, write tools and session management. Supports DashScope and Ali Token Plan. Soul enabled by default for AI personality evolution.",
   "type": "module",
   "bin": {