Refine getStatus/startNew v3 parity (review item 5)

- getStatus throws on not-found with a v3-style 'DurableClient error:' message (verified v3 DurableClient.getStatus throws on the extension's HTTP 404; returns non-optional DurableOrchestrationStatus).

- showInput now gates only the top-level input (payloads always fetched); output/customStatus are always returned, matching v3.

- showHistoryOutput now strips input/result payloads from history entries when falsy and keeps them when true. history stays core HistoryEvent[] (v3 types history as Array<unknown>).

- startNew forwards the v3 version option (already wired to core scheduleNewOrchestration).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: YunchuWang

packages/azure-functions-durable/CHANGELOG.md

@@ -19,11 +19,11 @@ Initial gRPC-consolidated Azure Functions Durable provider, built on `@microsoft
   `isCompleted` / `isFaulted` / `result`). `context.df.createTimer(...)` returns a cancelable
   `TimerTask`, so the timeout-race pattern (`Task.any` then `timer.cancel()`) keeps working.
 - `client.getStatus()` matches the v3 signature: it returns a non-optional `DurableOrchestrationStatus`
-  and throws when the instance does not exist. `showInput`, `showHistory`, and `showHistoryOutput` are
-  accepted, with two consolidated-path caveats: `showInput` maps to the core `fetchPayloads` flag (so
-  `showInput: false` also omits output/custom status, where v3 omitted only the input), and
-  `showHistory` surfaces core `HistoryEvent`s rather than the classic .NET extension's history shape
-  (`showHistoryOutput` is accepted but does not strip payloads on the gRPC path).
+  and throws when the instance does not exist. `showInput` suppresses only the top-level input (output
+  and custom status are always returned, as in v3); `showHistory` populates `history`, and
+  `showHistoryOutput` toggles whether those entries keep their input/result payloads. One
+  consolidated-path note: `history` entries are core `HistoryEvent`s (v3 types `history` as
+  `Array<unknown>`), not the classic .NET extension's history serialization.
 - `client.startNew()` supports the v3 `version` option (forwarded to the core scheduler).
 - Removed top-level exports: `DummyOrchestrationContext`, `DummyEntityContext`, `DurableError`,
   `AggregatedError`, `ManagedIdentityTokenSource`, `TokenSource`. `TaskFailedError` is re-exported

packages/azure-functions-durable/README.md

@@ -34,10 +34,10 @@ changed. See [`CHANGELOG.md`](./CHANGELOG.md) for the full list; the highlights:
   of v3's `isCompleted` / `isFaulted` / `result`. `context.df.createTimer(...)` still returns a
   cancelable `TimerTask` for the timeout-race pattern.
 - **`client.getStatus()` keeps the v3 shape** — it returns a non-optional `DurableOrchestrationStatus`
-  and throws when the instance is missing. `showInput` / `showHistory` / `showHistoryOutput` are
-  accepted, but `showInput` also gates output/custom status and `showHistory` returns core
-  `HistoryEvent`s (not the v3 extension history shape). **`client.startNew()` supports the `version`
-  option.**
+  and throws when the instance is missing. `showInput` suppresses only the top-level input,
+  `showHistory` populates `history`, and `showHistoryOutput` toggles the per-entry input/result
+  payloads; `history` entries are core `HistoryEvent`s (v3 types `history` as `Array<unknown>`).
+  **`client.startNew()` supports the `version` option.**
 - **Some v3 top-level exports were removed** — `DummyOrchestrationContext` / `DummyEntityContext`,
   `DurableError` / `AggregatedError`, and `ManagedIdentityTokenSource` / `TokenSource`.
   `TaskFailedError` is re-exported from the core SDK; use the core `TestOrchestrationWorker` /

packages/azure-functions-durable/src/client.ts

@@ -42,9 +42,8 @@ export interface GetStatusOptions {
   /** Include the execution history in {@link DurableOrchestrationStatus.history}. */
   showHistory?: boolean;
   /**
-   * Include input/output payloads in the history entries. Accepted for v3 compatibility; on the
-   * consolidated gRPC path the core history events always carry their payloads (see
-   * {@link DurableFunctionsClient.getStatus}).
+   * Include the input/result payloads on the history entries. When omitted or `false`, those
+   * payloads are stripped from each entry (see {@link DurableFunctionsClient.getStatus}).
    */
   showHistoryOutput?: boolean;
   /** Include the orchestration input/output/custom-status payloads (maps to core `fetchPayloads`). */
@@ -61,6 +60,21 @@ export interface StartNewOptions {
   version?: string;
 }
 
+/**
+ * @hidden
+ * Removes the input/result payload fields from a core history event, honoring v3's
+ * `showHistoryOutput: false`. Returns a shallow copy so the source event is left untouched.
+ */
+function stripHistoryEventOutput(event: unknown): unknown {
+  if (event !== null && typeof event === "object") {
+    const clone: Record<string, unknown> = { ...(event as Record<string, unknown>) };
+    delete clone.input;
+    delete clone.result;
+    return clone;
+  }
+  return event;
+}
+
 export class DurableFunctionsClient extends TaskHubGrpcClient {
   public readonly taskHubName: string;
   public readonly connectionName: string;
@@ -197,29 +211,36 @@ export class DurableFunctionsClient extends TaskHubGrpcClient {
    * @param instanceId - The ID of the orchestration instance to query.
    * @param options - v3 {@link GetStatusOptions}: `showInput`, `showHistory`, `showHistoryOutput`.
    * @returns The instance status.
-   * @throws If no orchestration instance with the given ID exists (matches v3, which threw on the
-   *   extension's HTTP 404 response).
+   * @throws If no orchestration instance with the given ID exists. This matches v3's
+   *   `DurableClient.getStatus`, which throws on the extension's HTTP 404 not-found response.
    *
    * @remarks
-   * v3 parity and its boundaries on the consolidated gRPC path:
+   * v3 parity, verified against `azure-functions-durable-js`'s `DurableClient.getStatus`:
    * - Returns a non-optional {@link DurableOrchestrationStatus} and throws when the instance is not
-   *   found, exactly like v3's `DurableClient.getStatus`.
+   *   found, exactly like v3 (its `case 404` branch throws).
+   * - `showInput` gates only the top-level `input`: v3 keeps output/custom status regardless, so the
+   *   payloads are always fetched and only `input` is suppressed when `showInput === false`.
    * - `showHistory` populates {@link DurableOrchestrationStatus.history} from the core execution
-   *   history (`getOrchestrationHistory`). The entries are core `HistoryEvent`s, not the classic
-   *   .NET extension's history shape (the gRPC path bypasses the extension's HTTP history formatter).
-   * - `showHistoryOutput` is accepted for API compatibility but does not strip payloads from the
-   *   history events: core history events always carry their intrinsic input/output.
-   * - `showInput` maps to the core `fetchPayloads` flag. Because that call fetches input, output, and
-   *   custom status together, `showInput: false` also omits output/custom status (v3 omitted only the
-   *   input).
+   *   history (`getOrchestrationHistory`). v3 types `history` as `Array<unknown>`, so the entries are
+   *   core `HistoryEvent`s. On the consolidated gRPC path these are the core event shape, not the
+   *   classic .NET extension's history serialization (the gRPC path bypasses that HTTP formatter).
+   * - `showHistoryOutput` controls whether the history entries carry their input/result payloads:
+   *   when falsy, those fields are stripped from each event; when `true`, they are kept.
    */
   async getStatus(instanceId: string, options?: GetStatusOptions): Promise<DurableOrchestrationStatus> {
-    const state = await this.getOrchestrationState(instanceId, options?.showInput ?? true);
+    const state = await this.getOrchestrationState(instanceId, true);
     if (state === undefined) {
-      throw new Error(`No orchestration instance with ID '${instanceId}' was found.`);
+      throw new Error(
+        `DurableClient error: No orchestration instance with ID '${instanceId}' was found. ` +
+          `This usually means no data is associated with the provided instanceId.`,
+      );
+    }
+    let history: unknown[] | undefined;
+    if (options?.showHistory) {
+      const events = await this.getOrchestrationHistory(instanceId);
+      history = options.showHistoryOutput ? events : events.map(stripHistoryEventOutput);
     }
-    const history = options?.showHistory ? await this.getOrchestrationHistory(instanceId) : undefined;
-    return toDurableOrchestrationStatus(state, history);
+    return toDurableOrchestrationStatus(state, history, options?.showInput ?? true);
   }
 
   /**

packages/azure-functions-durable/src/orchestration-status.ts

@@ -110,19 +110,22 @@ export function fromOrchestrationRuntimeStatus(status: OrchestrationRuntimeStatu
  *
  * @param state - The core orchestration state to map.
  * @param history - Optional execution history to attach (see {@link DurableFunctionsClient.getStatus}
- *   `showHistory`). The entries are core {@link OrchestrationState} history events; the consolidated
- *   gRPC path surfaces core `HistoryEvent`s rather than the classic .NET extension's history shape.
+ *   `showHistory`). The entries are core `HistoryEvent`s; the consolidated gRPC path surfaces those
+ *   rather than the classic .NET extension's history shape (v3 types `history` as `Array<unknown>`).
+ * @param includeInput - When `false`, the top-level `input` is omitted (maps to v3's `showInput`,
+ *   which suppresses only the input while still returning output/custom status). Defaults to `true`.
  */
 export function toDurableOrchestrationStatus(
   state: OrchestrationState,
   history?: unknown[],
+  includeInput = true,
 ): DurableOrchestrationStatus {
   return new DurableOrchestrationStatus({
     name: state.name,
     instanceId: state.instanceId,
     createdTime: state.createdAt,
     lastUpdatedTime: state.lastUpdatedAt,
-    input: parseJson(state.serializedInput),
+    input: includeInput ? parseJson(state.serializedInput) : undefined,
     output: parseJson(state.serializedOutput),
     runtimeStatus: toOrchestrationRuntimeStatus(state.runtimeStatus),
     customStatus: parseJson(state.serializedCustomStatus),

packages/azure-functions-durable/test/unit/client.spec.ts

@@ -290,12 +290,13 @@ describe("DurableFunctionsClient", () => {
         undefined,
       );
 
-    it("getStatus returns a non-optional DurableOrchestrationStatus and honors showInput", async () => {
+    it("getStatus returns a non-optional DurableOrchestrationStatus and gates only input via showInput", async () => {
       const client = new DurableFunctionsClient(CLIENT_CONFIG);
       try {
         const getState = jest.spyOn(client, "getOrchestrationState").mockResolvedValue(makeState());
 
         const status = await client.getStatus("inst-1");
+        // Payloads are always fetched; showInput only gates the top-level input (v3 keeps output).
         expect(getState).toHaveBeenCalledWith("inst-1", true);
         expect(status.instanceId).toBe("inst-1");
         expect(status.name).toBe("MyOrch");
@@ -304,9 +305,11 @@ describe("DurableFunctionsClient", () => {
         expect(status.output).toBe("the-output");
         expect(status.history).toBeUndefined();
 
-        // showInput maps to the core fetchPayloads flag.
-        await client.getStatus("inst-1", { showInput: false });
-        expect(getState).toHaveBeenLastCalledWith("inst-1", false);
+        // showInput: false suppresses only input; output/custom status still come back.
+        const suppressed = await client.getStatus("inst-1", { showInput: false });
+        expect(getState).toHaveBeenLastCalledWith("inst-1", true);
+        expect(suppressed.input).toBeUndefined();
+        expect(suppressed.output).toBe("the-output");
       } finally {
         await client.stop();
       }
@@ -324,16 +327,27 @@ describe("DurableFunctionsClient", () => {
       }
     });
 
-    it("getStatus populates history from the core execution history when showHistory is set", async () => {
+    it("getStatus populates history and honors showHistoryOutput", async () => {
       const client = new DurableFunctionsClient(CLIENT_CONFIG);
       try {
         jest.spyOn(client, "getOrchestrationState").mockResolvedValue(makeState());
-        const events = [{ eventId: 1 }, { eventId: 2 }];
+        const events = [
+          { eventId: 1, type: "TaskCompleted", input: "in", result: "out" },
+          { eventId: 2, type: "TimerFired" },
+        ];
         const getHistory = jest.spyOn(client, "getOrchestrationHistory").mockResolvedValue(events as never);
 
-        const status = await client.getStatus("inst-1", { showHistory: true });
+        // showHistoryOutput: true keeps the input/result payloads on each entry.
+        const withOutput = await client.getStatus("inst-1", { showHistory: true, showHistoryOutput: true });
         expect(getHistory).toHaveBeenCalledWith("inst-1");
-        expect(status.history).toEqual(events);
+        expect(withOutput.history).toEqual(events);
+
+        // showHistory without showHistoryOutput strips input/result from each entry.
+        const stripped = await client.getStatus("inst-1", { showHistory: true });
+        expect(stripped.history).toEqual([
+          { eventId: 1, type: "TaskCompleted" },
+          { eventId: 2, type: "TimerFired" },
+        ]);
 
         // Without showHistory the core history call is skipped and history stays undefined.
         getHistory.mockClear();