@syengup/friday-channel-next 0.1.37 → 0.1.38

package/dist/src/agent/operator-scope.d.ts

@@ -0,0 +1,19 @@
+type ScopeLike = {
+    client?: {
+        connect?: {
+            scopes?: unknown;
+        };
+    };
+} | null | undefined;
+/**
+ * Adds the required operator scopes to a gateway-request-scope's
+ * `client.connect.scopes` array in place. Pure and idempotent.
+ * Returns the scopes that were actually added (empty if none / no array present).
+ */
+export declare function elevateScopeForSubagentSpawn(scope: ScopeLike): string[];
+/**
+ * Fetches the live plugin gateway-request-scope and elevates it so the dispatched
+ * agent can spawn subagents. Never throws — returns the scopes added (or []).
+ */
+export declare function ensureSubagentSpawnScope(): string[];
+export {};

package/dist/src/agent/operator-scope.js

@@ -0,0 +1,54 @@
+// Operator-scope elevation for friday-next agent dispatch.
+//
+// Why this exists: friday-next registers all its routes with auth:"plugin" (it does
+// its own device-token auth, not the gateway operator token). Core's
+// createPluginRouteRuntimeScope gives auth!="gateway" routes an EMPTY operator-scope
+// set. When an agent dispatched from such a route spawns a subagent, the spawn
+// re-enters the in-process gateway `agent` method, which requires `operator.write`
+// (core-descriptors: { name:"agent", scope:"operator.write" }). With an empty ambient
+// scope the spawn fails with `{"error":"missing scope: operator.write"}`.
+//
+// The subagent spawn reads getPluginRuntimeGatewayRequestScope() at spawn time and
+// uses that scope's client for authorization. Because AsyncLocalStorage returns the
+// SAME store object reference, mutating its client.connect.scopes once — before we
+// kick off the dispatch, while still inside the route's ALS context — propagates the
+// elevated scopes to every later reader, including the subagent spawn.
+//
+// Subagent lifecycle admin methods (sessions.patch/delete) are unaffected: core pins
+// those to ADMIN_SCOPE via a synthetic client, so only the `agent` method depends on
+// this ambient operator.write. See memory: subagent-spawn-missing-operator-write.
+import { getPluginRuntimeGatewayRequestScope } from "openclaw/plugin-sdk/plugin-runtime";
+/** Operator scopes the friday-next dispatch needs so agents can spawn subagents. */
+const REQUIRED_OPERATOR_SCOPES = ["operator.write", "operator.read"];
+/**
+ * Adds the required operator scopes to a gateway-request-scope's
+ * `client.connect.scopes` array in place. Pure and idempotent.
+ * Returns the scopes that were actually added (empty if none / no array present).
+ */
+export function elevateScopeForSubagentSpawn(scope) {
+    const connect = scope?.client?.connect;
+    if (!connect || !Array.isArray(connect.scopes)) {
+        return [];
+    }
+    const scopes = connect.scopes;
+    const added = [];
+    for (const scopeName of REQUIRED_OPERATOR_SCOPES) {
+        if (!scopes.includes(scopeName)) {
+            scopes.push(scopeName);
+            added.push(scopeName);
+        }
+    }
+    return added;
+}
+/**
+ * Fetches the live plugin gateway-request-scope and elevates it so the dispatched
+ * agent can spawn subagents. Never throws — returns the scopes added (or []).
+ */
+export function ensureSubagentSpawnScope() {
+    try {
+        return elevateScopeForSubagentSpawn(getPluginRuntimeGatewayRequestScope());
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/http/handlers/messages.js

@@ -21,6 +21,7 @@ import { registerFridaySessionDeviceMapping } from "../../friday-session.js";
 import { touchFridayInbound } from "../../friday-inbound-stats.js";
 import { fridayAttachmentLookupKey, fridayFilesPublicUrl, readFile, rememberInboundMediaName, resolveMediaAttachment, resolveMediaUrl, } from "./files.js";
 import { runFridayDispatch } from "../../agent/dispatch-bridge.js";
+import { ensureSubagentSpawnScope } from "../../agent/operator-scope.js";
 import { saveInboundMediaBuffer } from "../../agent/media-bridge.js";
 import { contextTokensFromUsageRecord, getRunMetadata, getRunRoute, hasRunFinalDelivered, markRunFinalDelivered, registerRunRoute, setRunMetadata, } from "../../run-metadata.js";
 import { createFridayNextLogger, setFridayNextLogLevel } from "../../logging.js";
@@ -506,6 +507,14 @@ export async function handleMessages(req, res) {
             sseEmitter.untrackRun(runId);
         }
     };
+    // Elevate the route's (empty) operator scope so the dispatched agent can spawn
+    // subagents. Must run here, synchronously inside the route's AsyncLocalStorage
+    // context, so the live scope object the subagent spawn later reads carries
+    // operator.write. See agent/operator-scope.ts.
+    const elevatedScopes = ensureSubagentSpawnScope();
+    if (elevatedScopes.length > 0) {
+        log("SCOPE_ELEVATED", normalizedDeviceId, runId, elevatedScopes.join(","));
+    }
     runAgent().catch((err) => {
         log("RUN_ERROR", normalizedDeviceId, runId, String(err), "error");
         sseEmitter.untrackRun(runId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syengup/friday-channel-next",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "description": "OpenClaw Friday Next Apple channel plugin",
   "license": "MIT",
   "type": "module",

package/src/agent/operator-scope.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, vi } from "vitest";
+
+// The helper imports the live scope getter from core; the pure function under test
+// never calls it, but the module-level import must resolve. Mock it so the unit test
+// does not depend on the OpenClaw dist runtime.
+const getScope = vi.fn();
+vi.mock("openclaw/plugin-sdk/plugin-runtime", () => ({
+  getPluginRuntimeGatewayRequestScope: () => getScope(),
+}));
+
+import { elevateScopeForSubagentSpawn, ensureSubagentSpawnScope } from "./operator-scope.js";
+
+function makeScope(scopes: string[]) {
+  return { client: { connect: { role: "operator", scopes } } };
+}
+
+describe("elevateScopeForSubagentSpawn", () => {
+  it("adds operator.write + operator.read to an empty plugin-route scope", () => {
+    // friday-next routes register with auth:"plugin", which core gives EMPTY operator
+    // scopes. Subagent spawn re-enters the gateway `agent` method (requires
+    // operator.write) and fails with "missing scope: operator.write" without this.
+    const scope = makeScope([]);
+    const added = elevateScopeForSubagentSpawn(scope);
+    expect(scope.client.connect.scopes).toContain("operator.write");
+    expect(scope.client.connect.scopes).toContain("operator.read");
+    expect(added).toEqual(["operator.write", "operator.read"]);
+  });
+
+  it("is idempotent — does not duplicate already-present scopes", () => {
+    const scope = makeScope(["operator.write"]);
+    const added = elevateScopeForSubagentSpawn(scope);
+    expect(added).toEqual(["operator.read"]);
+    expect(scope.client.connect.scopes.filter((s) => s === "operator.write")).toHaveLength(1);
+  });
+
+  it("preserves unrelated existing scopes", () => {
+    const scope = makeScope(["operator.admin"]);
+    elevateScopeForSubagentSpawn(scope);
+    expect(scope.client.connect.scopes).toContain("operator.admin");
+    expect(scope.client.connect.scopes).toContain("operator.write");
+  });
+
+  it("returns [] and never throws when no scope/client is present", () => {
+    expect(elevateScopeForSubagentSpawn(undefined)).toEqual([]);
+    expect(elevateScopeForSubagentSpawn(null)).toEqual([]);
+    expect(elevateScopeForSubagentSpawn({})).toEqual([]);
+    expect(elevateScopeForSubagentSpawn({ client: { connect: {} } })).toEqual([]);
+  });
+});
+
+describe("ensureSubagentSpawnScope", () => {
+  it("elevates the live scope returned by the SDK getter", () => {
+    const scope = makeScope([]);
+    getScope.mockReturnValue(scope);
+    const added = ensureSubagentSpawnScope();
+    expect(added).toEqual(["operator.write", "operator.read"]);
+    expect(scope.client.connect.scopes).toContain("operator.write");
+  });
+
+  it("swallows errors from the getter and returns []", () => {
+    getScope.mockImplementation(() => {
+      throw new Error("no scope");
+    });
+    expect(ensureSubagentSpawnScope()).toEqual([]);
+  });
+});

package/src/agent/operator-scope.ts

@@ -0,0 +1,63 @@
+// Operator-scope elevation for friday-next agent dispatch.
+//
+// Why this exists: friday-next registers all its routes with auth:"plugin" (it does
+// its own device-token auth, not the gateway operator token). Core's
+// createPluginRouteRuntimeScope gives auth!="gateway" routes an EMPTY operator-scope
+// set. When an agent dispatched from such a route spawns a subagent, the spawn
+// re-enters the in-process gateway `agent` method, which requires `operator.write`
+// (core-descriptors: { name:"agent", scope:"operator.write" }). With an empty ambient
+// scope the spawn fails with `{"error":"missing scope: operator.write"}`.
+//
+// The subagent spawn reads getPluginRuntimeGatewayRequestScope() at spawn time and
+// uses that scope's client for authorization. Because AsyncLocalStorage returns the
+// SAME store object reference, mutating its client.connect.scopes once — before we
+// kick off the dispatch, while still inside the route's ALS context — propagates the
+// elevated scopes to every later reader, including the subagent spawn.
+//
+// Subagent lifecycle admin methods (sessions.patch/delete) are unaffected: core pins
+// those to ADMIN_SCOPE via a synthetic client, so only the `agent` method depends on
+// this ambient operator.write. See memory: subagent-spawn-missing-operator-write.
+import { getPluginRuntimeGatewayRequestScope } from "openclaw/plugin-sdk/plugin-runtime";
+
+/** Operator scopes the friday-next dispatch needs so agents can spawn subagents. */
+const REQUIRED_OPERATOR_SCOPES = ["operator.write", "operator.read"] as const;
+
+type ScopeLike =
+  | {
+      client?: { connect?: { scopes?: unknown } };
+    }
+  | null
+  | undefined;
+
+/**
+ * Adds the required operator scopes to a gateway-request-scope's
+ * `client.connect.scopes` array in place. Pure and idempotent.
+ * Returns the scopes that were actually added (empty if none / no array present).
+ */
+export function elevateScopeForSubagentSpawn(scope: ScopeLike): string[] {
+  const connect = scope?.client?.connect;
+  if (!connect || !Array.isArray(connect.scopes)) {
+    return [];
+  }
+  const scopes = connect.scopes as string[];
+  const added: string[] = [];
+  for (const scopeName of REQUIRED_OPERATOR_SCOPES) {
+    if (!scopes.includes(scopeName)) {
+      scopes.push(scopeName);
+      added.push(scopeName);
+    }
+  }
+  return added;
+}
+
+/**
+ * Fetches the live plugin gateway-request-scope and elevates it so the dispatched
+ * agent can spawn subagents. Never throws — returns the scopes added (or []).
+ */
+export function ensureSubagentSpawnScope(): string[] {
+  try {
+    return elevateScopeForSubagentSpawn(getPluginRuntimeGatewayRequestScope());
+  } catch {
+    return [];
+  }
+}

package/src/http/handlers/messages.ts

@@ -48,6 +48,7 @@ import {
   resolveMediaUrl,
 } from "./files.js";
 import { runFridayDispatch } from "../../agent/dispatch-bridge.js";
+import { ensureSubagentSpawnScope } from "../../agent/operator-scope.js";
 import { saveInboundMediaBuffer } from "../../agent/media-bridge.js";
 import {
   contextTokensFromUsageRecord,
@@ -674,6 +675,15 @@ export async function handleMessages(req: IncomingMessage, res: ServerResponse):
     }
   };
 
+  // Elevate the route's (empty) operator scope so the dispatched agent can spawn
+  // subagents. Must run here, synchronously inside the route's AsyncLocalStorage
+  // context, so the live scope object the subagent spawn later reads carries
+  // operator.write. See agent/operator-scope.ts.
+  const elevatedScopes = ensureSubagentSpawnScope();
+  if (elevatedScopes.length > 0) {
+    log("SCOPE_ELEVATED", normalizedDeviceId, runId, elevatedScopes.join(","));
+  }
+
   runAgent().catch((err) => {
     log("RUN_ERROR", normalizedDeviceId, runId, String(err), "error");
     sseEmitter.untrackRun(runId);

package/src/openclaw.d.ts

@@ -93,6 +93,16 @@ declare module "openclaw/plugin-sdk/reply-dispatch-runtime" {
   export const dispatchReplyWithDispatcher: (...args: any[]) => any;
 }
 
+declare module "openclaw/plugin-sdk/plugin-runtime" {
+  /**
+   * Returns the request-local plugin gateway-request-scope (operator client/scopes,
+   * context) when called from within a plugin HTTP-route handler's async context.
+   */
+  export const getPluginRuntimeGatewayRequestScope: () =>
+    | { client?: { connect?: { scopes?: string[] } } }
+    | undefined;
+}
+
 declare module "openclaw/plugin-sdk/status-helpers" {
   export type ChannelAccountSnapshot = any;
 }