@openviking/openclaw-plugin 2026.6.2 → 2026.6.17-dev.2

package/client.ts

@@ -7,6 +7,12 @@ import { basename, dirname, join, relative } from "node:path";
 
 import { Zip, ZipDeflate } from "fflate";
 
+import { defaultHttpTransport, type HttpTransport } from "./adapters/http-transport.js";
+import {
+  defaultResourcePackager,
+  type ResourcePackager,
+} from "./adapters/resource-packager.js";
+
 export type FindResultItem = {
   uri: string;
   level?: number;
@@ -24,13 +30,22 @@ export type FindResult = {
   total?: number;
 };
 
+export type FsListEntry = string | Record<string, unknown>;
+
+export type FsListResult = FsListEntry[];
+
 export type CaptureMode = "semantic" | "keyword";
-export type ScopeName = "user" | "agent";
-export type AgentScopeMode = "user_agent" | "agent";
-export type RuntimeIdentity = {
-  userId: string;
-  agentId: string;
+function userSessionUri(sessionId: string): string {
+  return `viking://user/sessions/${encodeURIComponent(sessionId)}`;
+}
+
+export type OpenVikingClientOptions = {
+  transport?: HttpTransport;
+  resourcePackager?: ResourcePackager;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
 };
+
 export type CommitSessionResult = {
   session_id: string;
   /** "accepted" (async), "completed", "failed", or "timeout" (wait mode). */
@@ -44,6 +59,16 @@ export type CommitSessionResult = {
   trace_id?: string;
 };
 
+export type OVMemoryPolicySwitch = {
+  enabled?: boolean;
+};
+
+export type OVMemoryPolicy = {
+  self?: OVMemoryPolicySwitch;
+  peer?: OVMemoryPolicySwitch;
+  memory_types?: string[];
+};
+
 export type TaskResult = {
   task_id: string;
   task_type: string;
@@ -195,18 +220,8 @@ function sleep(ms: number): Promise<void> {
 }
 
 const MEMORY_URI_PATTERNS = [
-  /^viking:\/\/user\/(?:[^/]+(?:\/agent\/[^/]+)?\/)?memories(?:\/|$)/,
-  /^viking:\/\/agent\/(?:[^/]+(?:\/user\/[^/]+)?\/)?memories(?:\/|$)/,
+  /^viking:\/\/user\/(?:[^/]+\/)?memories(?:\/|$)/,
 ];
-const USER_STRUCTURE_DIRS = new Set(["memories", "profile.md", ".abstract.md", ".overview.md"]);
-const AGENT_STRUCTURE_DIRS = new Set([
-  "memories",
-  "skills",
-  "instructions",
-  "workspaces",
-  ".abstract.md",
-  ".overview.md",
-]);
 const REMOTE_RESOURCE_PREFIXES = ["http://", "https://", "git@", "ssh://", "git://"];
 
 export function isMemoryUri(uri: string): boolean {
@@ -238,7 +253,10 @@ async function cleanupUploadTempPath(path?: string): Promise<void> {
 }
 
 export class OpenVikingClient {
-  private identityCache = new Map<string, RuntimeIdentity>();
+  private readonly transport: HttpTransport;
+  private readonly now: () => number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly resourcePackager: ResourcePackager;
 
   constructor(
     private readonly baseUrl: string,
@@ -250,27 +268,24 @@ export class OpenVikingClient {
     private readonly userId: string = "",
     /** When set, logs routing for find + session writes (tenant headers + paths; never apiKey). */
     private readonly routingDebugLog?: (message: string) => void,
-    private readonly isolateUserScopeByAgent = false,
-    private readonly isolateAgentScopeByUser = true,
-  ) {}
+	    optionsOrLegacyUserScope: OpenVikingClientOptions | boolean = {},
+	    _legacyAgentScope?: boolean,
+	    legacyOptions?: OpenVikingClientOptions,
+	  ) {
+	    const options =
+	      typeof optionsOrLegacyUserScope === "object" && optionsOrLegacyUserScope !== null
+	        ? optionsOrLegacyUserScope
+	        : (legacyOptions ?? {});
+	    this.transport = options.transport ?? defaultHttpTransport;
+	    this.now = options.now ?? Date.now;
+	    this.sleep = options.sleep ?? sleep;
+    this.resourcePackager = options.resourcePackager ?? defaultResourcePackager;
+  }
 
   getDefaultAgentId(): string {
     return this.defaultAgentId;
   }
 
-  private resolveEffectiveAgentId(agentId?: string): string {
-    const explicit = agentId?.trim();
-    if (explicit) {
-      return explicit;
-    }
-    const prefix = this.defaultAgentId.trim();
-    return prefix ? `${prefix}_main` : "main";
-  }
-
-  async getResolvedIdentity(agentId?: string): Promise<RuntimeIdentity> {
-    return this.getRuntimeIdentity(agentId);
-  }
-
   private resolveTenantHeaders():
     | { apiKey?: string; accountId?: string; userId?: string }
   {
@@ -284,27 +299,35 @@ export class OpenVikingClient {
     };
   }
 
+  private resolveActorPeerHeader(actorPeerId?: string): string | undefined {
+    const value = actorPeerId?.trim();
+    return value || undefined;
+  }
+
+  private resolveDefaultActorPeerHeader(): string {
+    const peerPrefix = this.defaultAgentId.trim();
+    return peerPrefix ? `${peerPrefix}_main` : "main";
+  }
+
   private async emitRoutingDebug(
     label: string,
     detail: Record<string, unknown>,
-    agentId?: string,
+    actorPeerId?: string,
   ): Promise<void> {
     if (!this.routingDebugLog) {
       return;
     }
-    const effectiveAgentId = this.resolveEffectiveAgentId(agentId);
-    const identity = await this.getRuntimeIdentity(agentId);
     const tenantHeaders = this.resolveTenantHeaders();
+    const actorPeerHeader = this.resolveActorPeerHeader(actorPeerId);
     this.routingDebugLog(
       `openviking: ${label} ` +
         JSON.stringify({
           ...detail,
-          X_OpenViking_Agent: effectiveAgentId,
           X_OpenViking_Account: tenantHeaders.accountId ?? null,
           X_OpenViking_User: tenantHeaders.userId ?? null,
-          resolved_user_id: identity.userId,
+          X_OpenViking_Actor_Peer: actorPeerHeader ?? null,
           session_vfs_hint: detail.sessionId
-            ? `viking://session/${String(detail.sessionId)}`
+            ? userSessionUri(String(detail.sessionId))
             : undefined,
         }),
     );
@@ -313,10 +336,9 @@ export class OpenVikingClient {
   private async request<T>(
     path: string,
     init: RequestInit = {},
-    agentId?: string,
     requestTimeoutMs?: number,
+    actorPeerId?: string,
   ): Promise<T> {
-    const effectiveAgentId = this.resolveEffectiveAgentId(agentId);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), requestTimeoutMs ?? this.timeoutMs);
     try {
@@ -331,14 +353,15 @@ export class OpenVikingClient {
       if (tenantHeaders.userId) {
         headers.set("X-OpenViking-User", tenantHeaders.userId);
       }
-      if (effectiveAgentId) {
-        headers.set("X-OpenViking-Agent", effectiveAgentId);
+      const actorPeerHeader = this.resolveActorPeerHeader(actorPeerId);
+      if (actorPeerHeader) {
+        headers.set("X-OpenViking-Actor-Peer", actorPeerHeader);
       }
       if (init.body && !(init.body instanceof FormData) && !headers.has("Content-Type")) {
         headers.set("Content-Type", "application/json");
       }
 
-      const response = await fetch(`${this.baseUrl}${path}`, {
+      const response = await this.transport(`${this.baseUrl}${path}`, {
         ...init,
         headers,
         signal: controller.signal,
@@ -362,96 +385,81 @@ export class OpenVikingClient {
     }
   }
 
-  async healthCheck(agentId?: string, requestTimeoutMs?: number): Promise<void> {
-    await this.request<{ status: string }>("/health", {}, agentId, requestTimeoutMs);
-  }
-
-  private async getRuntimeIdentity(agentId?: string): Promise<RuntimeIdentity> {
-    const effectiveAgentId = this.resolveEffectiveAgentId(agentId);
-    const cached = this.identityCache.get(effectiveAgentId);
-    if (cached) {
-      return cached;
-    }
-    const fallback: RuntimeIdentity = { userId: "default", agentId: effectiveAgentId };
-    try {
-      const status = await this.request<{ user?: unknown }>("/api/v1/system/status", {}, agentId);
-      const userId =
-        typeof status.user === "string" && status.user.trim() ? status.user.trim() : "default";
-      const identity: RuntimeIdentity = { userId, agentId: effectiveAgentId };
-      this.identityCache.set(effectiveAgentId, identity);
-      return identity;
-    } catch {
-      this.identityCache.set(effectiveAgentId, fallback);
-      return fallback;
-    }
+  async healthCheck(requestTimeoutMs?: number, actorPeerId?: string): Promise<void> {
+    await this.request<{ status: string }>(
+      "/health",
+      {},
+      requestTimeoutMs,
+      actorPeerId ?? this.resolveDefaultActorPeerHeader(),
+    );
   }
 
-  private async buildCanonicalRoot(scope: ScopeName, agentId?: string): Promise<string> {
-    const identity = await this.getRuntimeIdentity(agentId);
-    if (scope === "user") {
-      const root = this.isolateUserScopeByAgent
-        ? `viking://user/${identity.userId}/agent/${identity.agentId}`
-        : `viking://user/${identity.userId}`;
-      return root;
+  async createSession(
+    sessionId: string,
+    options?: { memoryPolicy?: OVMemoryPolicy },
+  ): Promise<{ session_id: string; user?: unknown }> {
+    const body: Record<string, unknown> = { session_id: sessionId };
+    if (options?.memoryPolicy) {
+      body.memory_policy = options.memoryPolicy;
     }
-    const root = this.isolateAgentScopeByUser
-      ? `viking://agent/${identity.agentId}/user/${identity.userId}`
-      : `viking://agent/${identity.agentId}`;
-    return root;
+    return this.request<{ session_id: string; user?: unknown }>(
+      "/api/v1/sessions",
+      { method: "POST", body: JSON.stringify(body) },
+    );
   }
 
-  private async normalizeTargetUri(targetUri: string, agentId?: string): Promise<string> {
-    const trimmed = targetUri.trim().replace(/\/+$/, "");
-    const match = trimmed.match(/^viking:\/\/(user|agent)(?:\/(.*))?$/);
-    if (!match) {
-      return trimmed;
-    }
-    const scope = match[1] as ScopeName;
-    const rawRest = (match[2] ?? "").trim();
-    if (!rawRest) {
-      return trimmed;
-    }
-    const parts = rawRest.split("/").filter(Boolean);
-    if (parts.length === 0) {
-      return trimmed;
-    }
-
-    const reservedDirs = scope === "user" ? USER_STRUCTURE_DIRS : AGENT_STRUCTURE_DIRS;
-    if (!reservedDirs.has(parts[0]!)) {
-      return trimmed;
+  async ensureSession(
+    sessionId: string,
+    options?: { memoryPolicy?: OVMemoryPolicy },
+  ): Promise<boolean> {
+    try {
+      await this.createSession(sessionId, options);
+      return true;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.includes("[ALREADY_EXISTS]")) {
+        return false;
+      }
+      throw err;
     }
-
-    const root = await this.buildCanonicalRoot(scope, agentId);
-    return `${root}/${parts.join("/")}`;
   }
 
   async find(
     query: string,
     options: {
-      targetUri: string;
-      limit: number;
+      targetUri?: string;
+      limit?: number;
       scoreThreshold?: number;
+      contextType?: string | string[];
+      actorPeerId?: string;
     },
-    agentId?: string,
+    legacyActorPeerId?: string,
   ): Promise<FindResult> {
-    const normalizedTargetUri = await this.normalizeTargetUri(options.targetUri, agentId);
-    const body = {
+    const targetUri = options.targetUri?.trim().replace(/\/+$/, "") ?? "";
+    const body: {
+      query: string;
+      target_uri?: string;
+      limit?: number;
+      score_threshold?: number;
+      context_type?: string | string[];
+    } = {
       query,
-      target_uri: normalizedTargetUri,
       limit: options.limit,
       score_threshold: options.scoreThreshold,
+      context_type: options.contextType,
     };
-    const effectiveAgentId = this.resolveEffectiveAgentId(agentId);
-    const identity = await this.getRuntimeIdentity(agentId);
+    if (targetUri) {
+      body.target_uri = targetUri;
+    }
+    const actorPeerId = this.resolveActorPeerHeader(options.actorPeerId ?? legacyActorPeerId);
     const tenantHeaders = this.resolveTenantHeaders();
     this.routingDebugLog?.(
       `openviking: find POST ${this.baseUrl}/api/v1/search/find ` +
         JSON.stringify({
-          X_OpenViking_Agent: effectiveAgentId,
           X_OpenViking_Account: tenantHeaders.accountId ?? null,
           X_OpenViking_User: tenantHeaders.userId ?? null,
-          resolved_user_id: identity.userId,
-          target_uri: normalizedTargetUri,
+          X_OpenViking_Actor_Peer: actorPeerId ?? null,
+          target_uri: targetUri || null,
           target_uri_input: options.targetUri,
           query:
             query.length > 4000
@@ -459,19 +467,51 @@ export class OpenVikingClient {
               : query,
           limit: body.limit,
           score_threshold: body.score_threshold ?? null,
+          context_type: body.context_type ?? null,
         }),
     );
     return this.request<FindResult>("/api/v1/search/find", {
       method: "POST",
       body: JSON.stringify(body),
-    }, agentId);
+    }, undefined, actorPeerId);
   }
 
-  async read(uri: string, agentId?: string): Promise<string> {
+  async read(uri: string, actorPeerId?: string): Promise<string> {
     return this.request<string>(
       `/api/v1/content/read?uri=${encodeURIComponent(uri)}`,
       {},
-      agentId,
+      undefined,
+      actorPeerId,
+    );
+  }
+
+  async list(
+    uri: string,
+    options?: {
+      recursive?: boolean;
+      simple?: boolean;
+      output?: "agent" | "original";
+      absLimit?: number;
+      showAllHidden?: boolean;
+      nodeLimit?: number;
+      actorPeerId?: string;
+    },
+  ): Promise<FsListResult> {
+    const normalizedUri = uri.trim().replace(/\/+$/, "");
+    const params = new URLSearchParams({
+      uri: normalizedUri,
+      recursive: String(options?.recursive ?? false),
+      simple: String(options?.simple ?? false),
+      output: options?.output ?? "agent",
+      abs_limit: String(options?.absLimit ?? 256),
+      show_all_hidden: String(options?.showAllHidden ?? false),
+      node_limit: String(options?.nodeLimit ?? 1000),
+    });
+    return this.request<FsListResult>(
+      `/api/v1/fs/ls?${params.toString()}`,
+      {},
+      undefined,
+      options?.actorPeerId,
     );
   }
 
@@ -479,7 +519,6 @@ export class OpenVikingClient {
     sessionId: string,
     toolResultId: string,
     options?: { offset?: number; limit?: number; includeMetadata?: boolean },
-    agentId?: string,
   ): Promise<ToolResultReadResult> {
     const params = new URLSearchParams();
     if (options?.offset !== undefined) params.set("offset", String(options.offset));
@@ -491,7 +530,6 @@ export class OpenVikingClient {
     return this.request<ToolResultReadResult>(
       `/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(toolResultId)}${query ? `?${query}` : ""}`,
       {},
-      agentId,
     );
   }
 
@@ -500,7 +538,6 @@ export class OpenVikingClient {
     toolResultId: string,
     queryText: string,
     options?: { limit?: number; contextChars?: number },
-    agentId?: string,
   ): Promise<ToolResultSearchResult> {
     const params = new URLSearchParams({ q: queryText });
     if (options?.limit !== undefined) params.set("limit", String(options.limit));
@@ -510,14 +547,12 @@ export class OpenVikingClient {
     return this.request<ToolResultSearchResult>(
       `/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(toolResultId)}/search?${params.toString()}`,
       {},
-      agentId,
     );
   }
 
   async listToolResults(
     sessionId: string,
     options?: { toolName?: string; limit?: number },
-    agentId?: string,
   ): Promise<ToolResultListResult> {
     const params = new URLSearchParams();
     if (options?.toolName) params.set("tool_name", options.toolName);
@@ -526,22 +561,16 @@ export class OpenVikingClient {
     return this.request<ToolResultListResult>(
       `/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results${query ? `?${query}` : ""}`,
       {},
-      agentId,
     );
   }
 
-  async uploadTempFile(filePath: string, agentId?: string): Promise<string> {
-    const fileBytes = await readFile(filePath);
-    const form = new FormData();
-    form.append(
-      "file",
-      new Blob([toBlobPart(fileBytes)], { type: "application/octet-stream" }),
-      basename(filePath),
-    );
+  async uploadTempFile(filePath: string, actorPeerId?: string): Promise<string> {
+    const form = await this.resourcePackager.createTempUploadBody(filePath);
     const result = await this.request<{ temp_file_id: string }>(
       "/api/v1/resources/temp_upload",
       { method: "POST", body: form },
-      agentId,
+      undefined,
+      actorPeerId,
     );
     if (!result.temp_file_id) {
       throw new Error("OpenViking temp upload did not return temp_file_id");
@@ -606,7 +635,7 @@ export class OpenVikingClient {
     return zipPath;
   }
 
-  async addResource(input: AddResourceInput, agentId?: string): Promise<AddResourceResult> {
+  async addResource(input: AddResourceInput, actorPeerId?: string): Promise<AddResourceResult> {
     const pathOrUrl = input.pathOrUrl.trim();
     if (!pathOrUrl) {
       throw new Error("pathOrUrl is required");
@@ -631,36 +660,31 @@ export class OpenVikingClient {
       body.preserve_structure = input.preserveStructure;
     }
 
-    let cleanupPath: string | undefined;
+    let packagedSource: Awaited<ReturnType<ResourcePackager["prepareResourceSource"]>> | undefined;
     const requestTimeoutMs =
       input.wait ? resolveWaitRequestTimeoutMs(this.timeoutMs, input.timeout) : undefined;
     try {
-      if (isRemoteResourceSource(pathOrUrl)) {
-        body.path = pathOrUrl;
+      packagedSource = await this.resourcePackager.prepareResourceSource(pathOrUrl);
+      if (packagedSource.kind === "remote") {
+        body.path = packagedSource.path;
       } else {
-        const localStats = await stat(pathOrUrl);
-        let uploadPath = pathOrUrl;
-        if (localStats.isDirectory()) {
-          uploadPath = await this.zipDirectoryForUpload(pathOrUrl);
-          cleanupPath = uploadPath;
-          body.source_name = basename(pathOrUrl);
-        } else if (!localStats.isFile()) {
-          throw new Error(`Path is not a file or directory: ${pathOrUrl}`);
+        if (packagedSource.sourceName) {
+          body.source_name = packagedSource.sourceName;
         }
-        body.temp_file_id = await this.uploadTempFile(uploadPath, agentId);
+        body.temp_file_id = await this.uploadTempFile(packagedSource.uploadPath, actorPeerId);
       }
       return this.request<AddResourceResult>(
         "/api/v1/resources",
         { method: "POST", body: JSON.stringify(body) },
-        agentId,
         requestTimeoutMs,
+        actorPeerId,
       );
     } finally {
-      await cleanupUploadTempPath(cleanupPath);
+      await this.resourcePackager.cleanup(packagedSource);
     }
   }
 
-  async addSkill(input: AddSkillInput, agentId?: string): Promise<AddSkillResult> {
+  async addSkill(input: AddSkillInput, actorPeerId?: string): Promise<AddSkillResult> {
     const hasPath = typeof input.path === "string" && input.path.trim().length > 0;
     const hasData = input.data !== undefined && input.data !== null;
     if (hasPath === hasData) {
@@ -671,32 +695,28 @@ export class OpenVikingClient {
       wait: input.wait ?? false,
       timeout: input.timeout,
     };
-    let cleanupPath: string | undefined;
+    let packagedSource: Awaited<ReturnType<ResourcePackager["prepareLocalUploadSource"]>> | undefined;
     const requestTimeoutMs =
       input.wait ? resolveWaitRequestTimeoutMs(this.timeoutMs, input.timeout) : undefined;
     try {
       if (hasPath) {
         const skillPath = input.path!.trim();
-        const localStats = await stat(skillPath);
-        let uploadPath = skillPath;
-        if (localStats.isDirectory()) {
-          uploadPath = await this.zipDirectoryForUpload(skillPath);
-          cleanupPath = uploadPath;
-        } else if (!localStats.isFile()) {
+        packagedSource = await this.resourcePackager.prepareLocalUploadSource(skillPath);
+        if (packagedSource.kind !== "upload") {
           throw new Error(`Path is not a file or directory: ${skillPath}`);
         }
-        body.temp_file_id = await this.uploadTempFile(uploadPath, agentId);
+        body.temp_file_id = await this.uploadTempFile(packagedSource.uploadPath, actorPeerId);
       } else {
         body.data = input.data;
       }
       return this.request<AddSkillResult>(
         "/api/v1/skills",
         { method: "POST", body: JSON.stringify(body) },
-        agentId,
         requestTimeoutMs,
+        actorPeerId,
       );
     } finally {
-      await cleanupUploadTempPath(cleanupPath);
+      await this.resourcePackager.cleanup(packagedSource);
     }
   }
 
@@ -729,7 +749,7 @@ export class OpenVikingClient {
       abstract?: string;
       context_type?: "memory" | "resource" | "skill";
     }>,
-    agentId?: string,
+    actorPeerId?: string,
     createdAt?: string,
     roleId?: string,
   ): Promise<void> {
@@ -755,7 +775,7 @@ export class OpenVikingClient {
         partCount: parts.length,
         created_at: createdAt ?? null,
       },
-      agentId,
+      actorPeerId,
     );
     await this.request<{ session_id: string }>(
       `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
@@ -763,12 +783,13 @@ export class OpenVikingClient {
         method: "POST",
         body: JSON.stringify(body),
       },
-      agentId,
+      undefined,
+      actorPeerId,
     );
   }
 
   /** GET session — server auto-creates if absent; returns session meta including message stats and token usage. */
-  async getSession(sessionId: string, agentId?: string): Promise<{
+  async getSession(sessionId: string, actorPeerId?: string): Promise<{
     message_count?: number;
     commit_count?: number;
     last_commit_at?: string;
@@ -784,7 +805,8 @@ export class OpenVikingClient {
     }>(
       `/api/v1/sessions/${encodeURIComponent(sessionId)}`,
       { method: "GET" },
-      agentId,
+      undefined,
+      actorPeerId,
     );
   }
 
@@ -800,13 +822,13 @@ export class OpenVikingClient {
     options?: {
       wait?: boolean;
       timeoutMs?: number;
-      agentId?: string;
       /**
        * WM v2: number of most-recent messages to keep live after commit.
        * Forwarded as `keep_recent_count` in the POST body. 0 (default)
        * preserves the pre-v2 "archive everything" behavior.
-       */
+      */
       keepRecentCount?: number;
+      agentId?: string;
     },
   ): Promise<CommitSessionResult> {
     const keepRecentCount =
@@ -830,6 +852,7 @@ export class OpenVikingClient {
     const result = await this.request<CommitSessionResult>(
       `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
       { method: "POST", body: JSON.stringify(body) },
+      undefined,
       options?.agentId,
     );
 
@@ -838,10 +861,10 @@ export class OpenVikingClient {
     }
 
     // Client-side poll until Phase 2 finishes
-    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_PHASE2_POLL_TIMEOUT_MS);
+    const deadline = this.now() + (options.timeoutMs ?? DEFAULT_PHASE2_POLL_TIMEOUT_MS);
     const pollInterval = 500;
-    while (Date.now() < deadline) {
-      await sleep(pollInterval);
+    while (this.now() < deadline) {
+      await this.sleep(pollInterval);
       const task = await this.getTask(result.task_id, options.agentId).catch(() => null);
       if (!task) break;
       if (task.status === "completed") {
@@ -862,35 +885,38 @@ export class OpenVikingClient {
   }
 
   /** Poll a background task by ID. */
-  async getTask(taskId: string, agentId?: string): Promise<TaskResult> {
+  async getTask(taskId: string, actorPeerId?: string): Promise<TaskResult> {
     return this.request<TaskResult>(
       `/api/v1/tasks/${encodeURIComponent(taskId)}`,
       { method: "GET" },
-      agentId,
+      undefined,
+      actorPeerId,
     );
   }
 
   async getSessionContext(
     sessionId: string,
     tokenBudget: number = 128_000,
-    agentId?: string,
+    actorPeerId?: string,
   ): Promise<SessionContextResult> {
     return this.request(
       `/api/v1/sessions/${encodeURIComponent(sessionId)}/context?token_budget=${tokenBudget}`,
       { method: "GET" },
-      agentId,
+      undefined,
+      actorPeerId,
     );
   }
 
   async getSessionArchive(
     sessionId: string,
     archiveId: string,
-    agentId?: string,
+    actorPeerId?: string,
   ): Promise<SessionArchiveResult> {
     return this.request(
       `/api/v1/sessions/${encodeURIComponent(sessionId)}/archives/${encodeURIComponent(archiveId)}`,
       { method: "GET" },
-      agentId,
+      undefined,
+      actorPeerId,
     );
   }
 
@@ -902,7 +928,6 @@ export class OpenVikingClient {
       caseInsensitive?: boolean;
       nodeLimit?: number;
       levelLimit?: number;
-      agentId?: string;
     } = {},
   ): Promise<{
     matches: Array<{ line: number; uri: string; content: string }>;
@@ -910,7 +935,7 @@ export class OpenVikingClient {
     match_count?: number;
     files_scanned?: number;
   }> {
-    const baseUri = `viking://session/${sessionId}/history`;
+    const baseUri = `${userSessionUri(sessionId)}/history`;
     const uri = options.archiveId ? `${baseUri}/${options.archiveId}` : baseUri;
     return this.request(
       "/api/v1/search/grep",
@@ -924,16 +949,15 @@ export class OpenVikingClient {
           ...(options.levelLimit !== undefined ? { level_limit: options.levelLimit } : {}),
         }),
       },
-      options.agentId,
     );
   }
 
-  async deleteSession(sessionId: string, agentId?: string): Promise<void> {
-    await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" }, agentId);
+  async deleteSession(sessionId: string): Promise<void> {
+    await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" });
   }
-  async deleteUri(uri: string, agentId?: string): Promise<void> {
+  async deleteUri(uri: string, actorPeerId?: string): Promise<void> {
     await this.request(`/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=false`, {
       method: "DELETE",
-    }, agentId);
+    }, undefined, actorPeerId);
   }
 }