paseo-plugin-zcode-provider 0.4.1 → 0.4.3

package/README.md

@@ -81,12 +81,13 @@ The source baseline is `3c5b227649371507ddc4eb46ac5133afe6db1cab` (ZCode 3.16.2,
 - Models and reasoning options come from ZCode. Editing modes are `build`, `edit`, `guarded` and `yolo`; `settings.plan_mode` is independent. `guarded` (ZCode's Autonomous mode, Server 3.15.1 or later) runs tools without approval but asks once, each time, before a command that ZCode's safety rules consider risky; it is not offered on older runtimes.
 - Text, thoughts, tools, subagent progress, usage and history use V4 snapshots and deltas. Tool output is marked when ZCode truncates it. Usage is cumulative; repeated snapshots do not add it again.
 - Text submitted during generation uses native guidance. Attachments use the native queue. Paseo reports one run across these native turns and completes it only after all accepted input has been consumed and foreground work has ended.
+- Paseo sends every message typed in the app during a run as a steer that asks to clear pending permissions. The plugin queues it first, then declines pending permissions, questions and Plan approvals with their deny action until ZCode reads the message, including requests opened in the meantime. Requests that appear after it is read are left to the user. Declining a Plan approval in Plan mode ends ZCode's turn; the message then starts the next native turn in the same Paseo run (ADR 22).
 - Acceptance is reported once, after the native acknowledgement. Unknown delivery results are never automatically resent. Stop identifies the current native execution, disables automatic queue execution and removes pending input. A new explicit run enables the queue again.
 - As in ZCode Desktop, successful hooks are not shown. A finished hook invocation appears once, as a notification, only when a hook was blocked, failed, timed out or was cancelled; context compaction also appears once, when it ends. Paseo appends every notification it receives, so progress is not reported.
 - Native permission IDs, option values, questions and Plan approval retain their meanings. Question auto-resolution is disabled for each owned Server. Workspace hook trust is reviewed through the official CLI; it is not represented as “allow once.”
 - Each session owns its Server process and environment. Metadata requests use temporary Servers. Closing stdin gives ZCode time to clean up before process termination.
 
-The plugin uses ZCode's own skills, MCP configuration and tools. Browser Use and Computer Use cannot run in the plugin's ZCode, even when ZCode Desktop has them enabled: the Computer Use helper accepts only the signed Desktop app, and only Desktop provides browsers. ZCode's Visualize (interactive views in the conversation) renders only in Desktop. The plugin therefore hides all three from the model (ADR 19, ADR 21); Desktop is not affected. Generic rewind, independent Paseo child agents, hook-review UI and Goal/Workflow controls are outside this migration. `prompt.output_schema`, custom system prompts and `persist:false` are unsupported. MCP `alwaysLoad` is unsupported; stdio MCP commands must be absolute paths. Provider options are unsupported: in Paseo 0.11 and later, `agents.providers.zcode.options` in Paseo's `config.json` makes sessions fail with `INVALID_CONFIGURATION`, and the `command` and `env` overrides there are not applied. Paseo does not show context usage reported before the first turn, and the plugin adds no substitute display; Coding Plan quota appears in Paseo 0.11's Usage screen (see [Coding Plan usage](#coding-plan-usage)).
+The plugin uses ZCode's own skills, MCP configuration and tools. Browser Use and Computer Use cannot run in the plugin's ZCode, even when ZCode Desktop has them enabled: the Computer Use helper accepts only the signed Desktop app, and only Desktop provides browsers. ZCode's Visualize (interactive views in the conversation) renders only in Desktop. The plugin therefore hides all three from the model (ADR 19, ADR 21); Desktop is not affected. Generic rewind, independent Paseo child agents, hook-review UI and Goal/Workflow controls are outside this migration. `prompt.output_schema`, custom system prompts and `persist:false` are unsupported. A system prompt makes session creation fail with `INVALID_CONFIGURATION` and a message explaining why, including one appended by Paseo's Orchestration → System prompt setting or by another plugin that adds one to new agents. MCP `alwaysLoad` is unsupported; stdio MCP commands must be absolute paths. Provider options are unsupported: in Paseo 0.11 and later, `agents.providers.zcode.options` in Paseo's `config.json` makes sessions fail with `INVALID_CONFIGURATION`, and the `command` and `env` overrides there are not applied. Paseo does not show context usage reported before the first turn, and the plugin adds no substitute display; Coding Plan quota appears in Paseo 0.11's Usage screen (see [Coding Plan usage](#coding-plan-usage)).
 
 ## Persistence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-plugin-zcode-provider",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Unofficial Paseo provider plugin for ZCode, using the official stdio Services Server of the integrated ZCode CLI.",
   "keywords": [
     "paseo",

package/server/build-info.ts

@@ -1,2 +1,2 @@
 // Generated from package.json by npm prepare / prebuild.
-export const PROVIDER_VERSION = "0.4.1";
+export const PROVIDER_VERSION = "0.4.3";

package/server/presentation.ts

@@ -233,6 +233,8 @@ export function usage(state: ConversationSnapshot): ProviderUsage {
 export interface PresentedInteraction {
   request: ProviderPermissionRequest;
   answer(response: ProviderPermissionResponse): Record<string, unknown>;
+  /** Native answer of the first deny action, without interrupting. */
+  decline: Record<string, unknown>;
 }
 export function presentInteraction(
   interaction: PendingInteraction,
@@ -262,7 +264,8 @@ export function presentInteraction(
         variant: behavior === "allow" ? "primary" : "danger",
       };
     });
-    if (!actions.some((a) => a.behavior === "deny"))
+    const deny = actions.find((a) => a.behavior === "deny");
+    if (!deny)
       throw new AdapterError(
         "NATIVE_PROTOCOL_ERROR",
         "ZCode permission has no deny option",
@@ -299,6 +302,7 @@ export function presentInteraction(
           );
         return { optionId: action.id };
       },
+      decline: { optionId: deny.id },
     };
   }
   if (p.sensitive)
@@ -414,6 +418,7 @@ export function presentInteraction(
           },
         };
       },
+      decline: { action: "decline" },
     };
   }
   return {
@@ -445,6 +450,7 @@ export function presentInteraction(
             content: answerContent(record(response.updatedInput?.answers)),
           };
     },
+    decline: { action: "decline" },
   };
 }
 

package/server/provider.ts

@@ -220,7 +220,9 @@ export class ZCodeConnection implements ProviderConnection {
         if (input.type === "session.prompt") {
           const promptEntry = entry ?? this.sessions.get(input.sessionId);
           if (promptEntry?.messages.get(input.prompt.clientMessageId)) return;
-          promptEntry?.messages.set(input.prompt.clientMessageId, true);
+          // The input was not admitted. Paseo's interrupt-and-replace fallback
+          // for an unavailable steer resends it with the same ID.
+          promptEntry?.messages.delete(input.prompt.clientMessageId);
           this.emit({
             type: "session.prompt_result",
             sessionId: input.sessionId,
@@ -374,11 +376,6 @@ export class ZCodeConnection implements ProviderConnection {
     switch (input.type) {
       case "session.prompt": {
         const prompt = input.prompt.input;
-        if (input.prompt.clearPendingPermissions)
-          throw new AdapterError(
-            "INTERACTION_UNSUPPORTED",
-            "Steering does not resolve pending ZCode permissions",
-          );
         if (input.prompt.delivery === "steer" && !entry.native.hasActiveTurn())
           throw new AdapterError(
             "SESSION_BUSY",
@@ -439,6 +436,7 @@ export class ZCodeConnection implements ProviderConnection {
           {
             clientMessageId: input.prompt.clientMessageId,
             delivery: input.prompt.delivery,
+            clearPendingPermissions: input.prompt.clearPendingPermissions,
             beforeSend: async () => {
               if (!entry.submitted) {
                 await this.persistenceStore.save(
@@ -497,7 +495,7 @@ export class ZCodeConnection implements ProviderConnection {
     if (config.systemPrompt?.trim())
       throw new AdapterError(
         "INVALID_CONFIGURATION",
-        "Custom system prompts are unsupported by the verified ZCode host",
+        "ZCode does not support custom system prompts. Remove any added by Paseo's System prompt setting (Orchestration) or by another plugin.",
       );
     if (!config.persist)
       throw new AdapterError(
@@ -814,12 +812,23 @@ function publicError(error: unknown): ProviderError {
     PERSISTENCE_WRITE_FAILED:
       "ZCode resume information could not be saved. The prompt was not sent.",
   };
+  // diagnosticError keeps the thrown error as the cause. Only a configuration
+  // reason the plugin raised itself is shown; wrapped native or unexpected
+  // failures keep the generic text.
+  const configurationReason =
+    error instanceof AdapterError &&
+    error.code === "INVALID_CONFIGURATION" &&
+    error.cause instanceof AdapterError
+      ? error.message
+      : undefined;
   return {
     diagnostic: formatDiagnostic(error),
     code: error instanceof AdapterError ? error.code : "INVALID_CONFIGURATION",
     message:
       error instanceof AdapterError
-        ? (messages[error.code] ?? `ZCode operation failed (${error.code})`)
+        ? (messages[error.code] ??
+          configurationReason ??
+          `ZCode operation failed (${error.code})`)
         : "Invalid ZCode provider request",
   };
 }

package/server/session.ts

@@ -55,6 +55,8 @@ interface Admission {
   accepted: boolean;
   consumed: boolean;
   productTurnId?: string;
+  /** Paseo's clearPendingPermissions: decline interactions until consumed. */
+  releasesInteractions?: boolean;
 }
 interface Run {
   id: string;
@@ -286,6 +288,7 @@ export class ZCodeSession {
         });
       }
     }
+    this.releaseInteractions();
     if (
       this.state.workspaceHookAdmission ||
       this.state.pendingInteractions.some(
@@ -323,6 +326,29 @@ export class ZCodeSession {
     }
     this.maybeComplete();
   }
+  /**
+   * ZCode reads a steer only after every tool call of the model step settles,
+   * so a parked turn never reads it. While an accepted steer that asked to clear
+   * permissions is unread, decline each pending interaction, including requests
+   * opened after an earlier decline.
+   */
+  private releaseInteractions(): void {
+    const run = this.active;
+    if (
+      !run ||
+      run.cancelled ||
+      ![...run.inputs.values()].some(
+        (i) => i.releasesInteractions && i.accepted && !i.consumed,
+      )
+    )
+      return;
+    for (const [id, interaction] of this.pending) {
+      if (this.answering.has(id)) continue;
+      this.resolveInteraction(id, interaction.decline).catch((error) =>
+        this.runtimeFailed(diagnosticError(error, this.bridge.diagnostic)),
+      );
+    }
+  }
   private maybeComplete(): void {
     const run = this.active;
     if (
@@ -537,6 +563,7 @@ export class ZCodeSession {
     options?: {
       clientMessageId: string;
       delivery?: "auto" | "steer";
+      clearPendingPermissions?: boolean;
       beforeSend?: () => Promise<void>;
     },
   ): Promise<{ turnId: string }> {
@@ -634,6 +661,7 @@ export class ZCodeSession {
         );
       this.assertOpen();
       input.accepted = true;
+      input.releasesInteractions = options?.clearPendingPermissions === true;
       if (options?.clientMessageId)
         this.emit({
           type: "prompt_accepted",
@@ -701,7 +729,12 @@ export class ZCodeSession {
         "SESSION_NOT_FOUND",
         "ZCode interaction is no longer pending",
       );
-    const answer = pending.answer(response);
+    await this.resolveInteraction(id, pending.answer(response));
+  }
+  private async resolveInteraction(
+    id: string,
+    answer: Record<string, unknown>,
+  ): Promise<void> {
     this.answering.add(id);
     try {
       await this.control("resolveInteraction", { interactionId: id, answer });