@neuralis/brain-core 0.1.0 → 0.2.1

package/app/filesystem/api/index.ts

@@ -21,12 +21,15 @@ import type {
 } from '../domain/types';
 
 /**
- * Await the PackageApi for 'brain-core'. Uses tryGetPackageApiImperativeAsync so
- * that callers invoked at mount time don't race the PackageApiProvider registration.
+ * Every request takes its `client` as the LAST argument: a Files window passes
+ * the one its store was built with — `createPackageApi` over the window's project
+ * and BOUND agent (`createFilesWindowStore`) — so the X-Project-Id / X-Agent-Id
+ * headers are the window's own, fixed before any await, whatever other Files
+ * window or agent is mounted beside it. A request body may still name another
+ * agent (a file read through its writing agent); the header plane stays the
+ * window's. `readFiles` alone accepts no client, for the chat change card, which
+ * is not a Files window and reads through the first registered provider.
  */
-function api(): Promise<PackageApi> {
-  return tryGetPackageApiImperativeAsync('brain-core');
-}
 
 export type ResolveListOpts = {
   /** Omit (or `/`) for the full-root view; otherwise a scope URI like `data://agent-core`. */
@@ -58,8 +61,9 @@ export type ResolveListOpts = {
 
 export async function resolveList(
   agentId: string,
-  projectId?: string,
-  opts?: ResolveListOpts,
+  projectId: string | undefined,
+  opts: ResolveListOpts,
+  client: PackageApi,
 ): Promise<{
   uri: string;
   folders: unknown[];
@@ -69,7 +73,6 @@ export async function resolveList(
   truncated?: boolean;
   summary_omitted_count?: number;
 }> {
-  const a = await api();
   const body: Record<string, unknown> = { agentId };
   if (projectId) body.projectId = projectId;
   if (opts?.uri) body.uri = opts.uri;
@@ -81,7 +84,7 @@ export async function resolveList(
   if (typeof opts?.sources_only === 'boolean') body.sources_only = opts.sources_only;
   if (typeof opts?.include_counts === 'boolean') body.include_counts = opts.include_counts;
   if (typeof opts?.limit === 'number') body.limit = opts.limit;
-  return a.post('list', body);
+  return client.post('list', body);
 }
 
 /**
@@ -95,6 +98,7 @@ export async function fetchSourceCounts(
   agentId: string,
   projectId: string | undefined,
   source: string,
+  client: PackageApi,
 ): Promise<SourceInfo | null> {
   const res = await resolveList(agentId, projectId, {
     uri: `${source}://`,
@@ -102,7 +106,7 @@ export async function fetchSourceCounts(
     include: 'folders',
     include_counts: true,
     limit: 1,
-  });
+  }, client);
   return res.sources?.[0] ?? null;
 }
 
@@ -112,8 +116,8 @@ export async function readFiles(params: {
   files: string[];
   /** `baseline` reads the pre-change snapshot (for the Changes diff card). */
   read_version?: 'current' | 'baseline';
-}): Promise<FSReadResponse> {
-  return (await api()).post('read', params);
+}, client?: PackageApi): Promise<FSReadResponse> {
+  return (client ?? await tryGetPackageApiImperativeAsync('brain-core')).post('read', params);
 }
 
 export async function listSourceConfigs(params: {
@@ -121,20 +125,20 @@ export async function listSourceConfigs(params: {
   projectId?: string;
   scope?: 'project' | 'user' | 'agent';
   observed?: boolean;
-}): Promise<SourceConfigRecord[]> {
+}, client: PackageApi): Promise<SourceConfigRecord[]> {
   const qs: Record<string, string> = { agentId: params.agentId };
   if (params.projectId) qs.projectId = params.projectId;
   if (params.scope) qs.scope = params.scope;
   if (params.observed) qs.observed = '1';
-  return (await api()).get('sources', qs);
+  return client.get('sources', qs);
 }
 
 export async function updateSourceConfig(params: {
   agentId: string;
   projectId?: string;
   config: UpdateSourceConfigRequest;
-}): Promise<SourceConfigRecord> {
-  return (await api()).patch('sources', {
+}, client: PackageApi): Promise<SourceConfigRecord> {
+  return client.patch('sources', {
     agentId: params.agentId,
     ...(params.projectId ? { projectId: params.projectId } : {}),
     ...params.config,
@@ -149,8 +153,8 @@ export async function triggerSourceSync(params: {
   agentId: string;
   projectId?: string;
   source: string;
-}): Promise<TriggerSourceSyncResponse> {
-  return (await api()).post('sources/sync', params);
+}, client: PackageApi): Promise<TriggerSourceSyncResponse> {
+  return client.post('sources/sync', params);
 }
 
 /** Queue job status for one source (or every visible source when omitted). */
@@ -158,11 +162,11 @@ export async function getSyncStatus(params: {
   agentId: string;
   projectId?: string;
   source?: string;
-}): Promise<{ source?: string; job?: SyncJobSnapshotRecord | null; jobs?: SyncJobSnapshotRecord[] }> {
+}, client: PackageApi): Promise<{ source?: string; job?: SyncJobSnapshotRecord | null; jobs?: SyncJobSnapshotRecord[] }> {
   const qs: Record<string, string> = { agentId: params.agentId };
   if (params.projectId) qs.projectId = params.projectId;
   if (params.source) qs.source = params.source;
-  return (await api()).get('sources/sync-status', qs);
+  return client.get('sources/sync-status', qs);
 }
 
 /**
@@ -174,8 +178,8 @@ export async function setSourceEnabled(params: {
   projectId?: string;
   source: string;
   enabled: boolean | 'auto';
-}): Promise<SourceConfigRecord> {
-  return (await api()).post('sources/enabled', {
+}, client: PackageApi): Promise<SourceConfigRecord> {
+  return client.post('sources/enabled', {
     agentId: params.agentId,
     ...(params.projectId ? { projectId: params.projectId } : {}),
     source: params.source,
@@ -237,11 +241,11 @@ export type DiscoverableSourceSuggestion = {
 export async function listDiscoverableSources(params: {
   agentId: string;
   projectId?: string;
-}): Promise<{ suggestions: DiscoverableSourceSuggestion[] }> {
+}, client: PackageApi): Promise<{ suggestions: DiscoverableSourceSuggestion[] }> {
   const qs = new URLSearchParams();
   qs.set('agentId', params.agentId);
   if (params.projectId) qs.set('projectId', params.projectId);
-  return (await api()).get('sources/discoverable', Object.fromEntries(qs));
+  return client.get('sources/discoverable', Object.fromEntries(qs));
 }
 
 // ---------------------------------------------------------------------------
@@ -283,10 +287,10 @@ export async function getGitRepos(params: {
   agentId: string;
   projectId?: string;
   source: string;
-}): Promise<{ ok: boolean; repos: GitRepoInfo[] }> {
+}, client: PackageApi): Promise<{ ok: boolean; repos: GitRepoInfo[] }> {
   const qs: Record<string, string> = { agentId: params.agentId, source: params.source };
   if (params.projectId) qs.projectId = params.projectId;
-  return (await api()).get('git/repos', qs);
+  return client.get('git/repos', qs);
 }
 
 /**
@@ -299,7 +303,7 @@ export async function getGitStatus(params: {
   projectId?: string;
   source: string;
   repo?: string;
-}): Promise<{
+}, client: PackageApi): Promise<{
   ok: boolean;
   status: GitControlStatus;
   /** Bucket `+/-` totals for the section headers, summed server-side over the
@@ -308,7 +312,7 @@ export async function getGitStatus(params: {
 }> {
   const qs: Record<string, string> = { agentId: params.agentId, source: params.source, ...repoQuery(params.repo) };
   if (params.projectId) qs.projectId = params.projectId;
-  return (await api()).get('git/status', qs);
+  return client.get('git/status', qs);
 }
 
 /** Local branch list for the (G2.3) branch-switcher. */
@@ -317,10 +321,10 @@ export async function getGitBranches(params: {
   projectId?: string;
   source: string;
   repo?: string;
-}): Promise<{ ok: boolean; branches: GitBranchInfo[]; truncated?: boolean }> {
+}, client: PackageApi): Promise<{ ok: boolean; branches: GitBranchInfo[]; truncated?: boolean }> {
   const qs: Record<string, string> = { agentId: params.agentId, source: params.source, ...repoQuery(params.repo) };
   if (params.projectId) qs.projectId = params.projectId;
-  return (await api()).get('git/branch', qs);
+  return client.get('git/branch', qs);
 }
 
 /**
@@ -356,7 +360,7 @@ export async function getGitDiff(params: {
   commit?: string;
   base?: string;
   head?: string;
-}): Promise<
+}, client: PackageApi): Promise<
   | {
       ok: true;
       diff: string;
@@ -390,7 +394,7 @@ export async function getGitDiff(params: {
   if (typeof params.head === 'string') qs.head = params.head;
   if (typeof params.staged === 'boolean') qs.staged = params.staged ? '1' : '0';
   if (params.projectId) qs.projectId = params.projectId;
-  return (await api()).get('git/diff', qs);
+  return client.get('git/diff', qs);
 }
 
 /**
@@ -414,13 +418,13 @@ export async function getGitLog(params: {
   maxCount?: number;
   skip?: number;
   ref?: string;
-}): Promise<{ ok: boolean; commits: GitGraphCommit[]; hasMore: boolean; outgoing?: string[] }> {
+}, client: PackageApi): Promise<{ ok: boolean; commits: GitGraphCommit[]; hasMore: boolean; outgoing?: string[] }> {
   const qs: Record<string, string> = { agentId: params.agentId, source: params.source, ...repoQuery(params.repo) };
   if (params.projectId) qs.projectId = params.projectId;
   if (typeof params.maxCount === 'number') qs.maxCount = String(params.maxCount);
   if (typeof params.skip === 'number') qs.skip = String(params.skip);
   if (params.ref) qs.ref = params.ref;
-  return (await api()).get('git/log', qs);
+  return client.get('git/log', qs);
 }
 
 /**
@@ -444,13 +448,13 @@ export async function getGitLogStats(params: {
   maxCount?: number;
   skip?: number;
   ref?: string;
-}): Promise<GitLogStatsResponse> {
+}, client: PackageApi): Promise<GitLogStatsResponse> {
   const qs: Record<string, string> = { agentId: params.agentId, source: params.source, ...repoQuery(params.repo) };
   if (params.projectId) qs.projectId = params.projectId;
   if (typeof params.maxCount === 'number') qs.maxCount = String(params.maxCount);
   if (typeof params.skip === 'number') qs.skip = String(params.skip);
   if (params.ref) qs.ref = params.ref;
-  return (await api()).get('git/log-stats', qs);
+  return client.get('git/log-stats', qs);
 }
 
 /**
@@ -469,7 +473,7 @@ export async function getGitCommitFiles(params: {
   source: string;
   repo?: string;
   sha: string;
-}): Promise<
+}, client: PackageApi): Promise<
   | { ok: true; sha: string; files: GitCommitFileChange[] }
   | { ok: false; code: 'unavailable'; sha: string }
 > {
@@ -480,7 +484,7 @@ export async function getGitCommitFiles(params: {
     sha: params.sha,
   };
   if (params.projectId) qs.projectId = params.projectId;
-  return (await api()).get('git/commit', qs);
+  return client.get('git/commit', qs);
 }
 
 /**
@@ -498,7 +502,7 @@ export async function getGitOutgoing(params: {
   projectId?: string;
   source: string;
   repo?: string;
-}): Promise<{
+}, client: PackageApi): Promise<{
   ok: boolean;
   // Present on the `ok:true` shapes (ready | honest no-upstream). A DEEP failure
   // (non-repo / unborn HEAD / any git error) is a typed refusal `{ok:false,
@@ -511,7 +515,7 @@ export async function getGitOutgoing(params: {
 }> {
   const qs: Record<string, string> = { agentId: params.agentId, source: params.source, ...repoQuery(params.repo) };
   if (params.projectId) qs.projectId = params.projectId;
-  return (await api()).get('git/outgoing', qs);
+  return client.get('git/outgoing', qs);
 }
 
 /**
@@ -531,7 +535,7 @@ export async function getGitShow(params: {
   repo?: string;
   path: string;
   rev: string;
-}): Promise<
+}, client: PackageApi): Promise<
   | { ok: true; content: string; path: string; rev: string }
   | { ok: false; code: 'not_a_blob' | 'too_large' | 'binary' | 'unavailable'; path: string; rev: string }
 > {
@@ -543,7 +547,7 @@ export async function getGitShow(params: {
     rev: params.rev,
   };
   if (params.projectId) qs.projectId = params.projectId;
-  return (await api()).get('git/show', qs);
+  return client.get('git/show', qs);
 }
 
 // ---------------------------------------------------------------------------
@@ -560,8 +564,6 @@ export async function getGitShow(params: {
 // recovered from), surfaced for the best-effort undo affordance.
 // ---------------------------------------------------------------------------
 
-const git = () => api();
-
 /**
  * The typed rescue carrier a destructive op returns (G2.5) — drives one-click
  * UNDO via `restoreGit`. `stash` → `git stash apply <ref>` (discarded content);
@@ -577,8 +579,8 @@ export async function stagePaths(params: {
   source: string;
   repo?: string;
   paths: string[];
-}): Promise<{ ok: boolean; staged: string[] | 'hunk' }> {
-  return (await git()).post('git/stage', {
+}, client: PackageApi): Promise<{ ok: boolean; staged: string[] | 'hunk' }> {
+  return client.post('git/stage', {
     source: params.source,
     ...repoBody(params.repo),
     paths: params.paths,
@@ -594,8 +596,8 @@ export async function unstagePaths(params: {
   source: string;
   repo?: string;
   paths: string[];
-}): Promise<{ ok: boolean; unstaged: string[] | 'hunk' }> {
-  return (await git()).post('git/unstage', {
+}, client: PackageApi): Promise<{ ok: boolean; unstaged: string[] | 'hunk' }> {
+  return client.post('git/unstage', {
     source: params.source,
     ...repoBody(params.repo),
     paths: params.paths,
@@ -614,8 +616,8 @@ export async function stageHunk(params: {
   source: string;
   repo?: string;
   hunk: string;
-}): Promise<{ ok: boolean; staged: string[] | 'hunk' }> {
-  return (await git()).post('git/stage', {
+}, client: PackageApi): Promise<{ ok: boolean; staged: string[] | 'hunk' }> {
+  return client.post('git/stage', {
     source: params.source,
     ...repoBody(params.repo),
     hunk: params.hunk,
@@ -631,8 +633,8 @@ export async function unstageHunk(params: {
   source: string;
   repo?: string;
   hunk: string;
-}): Promise<{ ok: boolean; unstaged: string[] | 'hunk' }> {
-  return (await git()).post('git/unstage', {
+}, client: PackageApi): Promise<{ ok: boolean; unstaged: string[] | 'hunk' }> {
+  return client.post('git/unstage', {
     source: params.source,
     ...repoBody(params.repo),
     hunk: params.hunk,
@@ -653,8 +655,8 @@ export async function discardPaths(params: {
   source: string;
   repo?: string;
   paths: string[];
-}): Promise<{ ok: boolean; discarded: string[]; rescue?: GitRescue }> {
-  return (await git()).post('git/discard', {
+}, client: PackageApi): Promise<{ ok: boolean; discarded: string[]; rescue?: GitRescue }> {
+  return client.post('git/discard', {
     source: params.source,
     ...repoBody(params.repo),
     paths: params.paths,
@@ -671,8 +673,8 @@ export async function commitGit(params: {
   repo?: string;
   message: string;
   amend?: boolean;
-}): Promise<{ ok: boolean; commit: string }> {
-  return (await git()).post('git/commit', {
+}, client: PackageApi): Promise<{ ok: boolean; commit: string }> {
+  return client.post('git/commit', {
     source: params.source,
     ...repoBody(params.repo),
     message: params.message,
@@ -690,8 +692,8 @@ export async function createGitBranch(params: {
   repo?: string;
   name: string;
   startPoint?: string;
-}): Promise<{ ok: boolean; branch: string; action: 'create' }> {
-  return (await git()).post('git/branch', {
+}, client: PackageApi): Promise<{ ok: boolean; branch: string; action: 'create' }> {
+  return client.post('git/branch', {
     source: params.source,
     ...repoBody(params.repo),
     action: 'create',
@@ -714,8 +716,8 @@ export async function deleteGitBranch(params: {
   repo?: string;
   name: string;
   force?: boolean;
-}): Promise<{ ok: boolean; branch: string; action: 'delete'; rescue?: GitRescue }> {
-  return (await git()).post('git/branch', {
+}, client: PackageApi): Promise<{ ok: boolean; branch: string; action: 'delete'; rescue?: GitRescue }> {
+  return client.post('git/branch', {
     source: params.source,
     ...repoBody(params.repo),
     action: 'delete',
@@ -738,8 +740,8 @@ export async function restoreGit(params: {
   source: string;
   repo?: string;
   rescue: GitRescue;
-}): Promise<{ ok: boolean; restored: 'stash' | 'branch' }> {
-  return (await git()).post('git/restore', {
+}, client: PackageApi): Promise<{ ok: boolean; restored: 'stash' | 'branch' }> {
+  return client.post('git/restore', {
     source: params.source,
     ...repoBody(params.repo),
     rescue: params.rescue,
@@ -758,8 +760,8 @@ export async function checkoutGitBranch(params: {
   source: string;
   repo?: string;
   ref: string;
-}): Promise<{ ok: boolean; checkout: string }> {
-  return (await git()).post('git/checkout', {
+}, client: PackageApi): Promise<{ ok: boolean; checkout: string }> {
+  return client.post('git/checkout', {
     source: params.source,
     ...repoBody(params.repo),
     ref: params.ref,
@@ -781,8 +783,8 @@ export async function fetchGit(params: {
   projectId?: string;
   source: string;
   repo?: string;
-}): Promise<{ ok: boolean; op: 'fetch'; host: string; status?: GitControlStatus }> {
-  return (await git()).post('git/fetch', {
+}, client: PackageApi): Promise<{ ok: boolean; op: 'fetch'; host: string; status?: GitControlStatus }> {
+  return client.post('git/fetch', {
     source: params.source,
     ...repoBody(params.repo),
     ...(params.projectId ? { projectId: params.projectId } : {}),
@@ -796,8 +798,8 @@ export async function pullGit(params: {
   projectId?: string;
   source: string;
   repo?: string;
-}): Promise<{ ok: boolean; op: 'pull'; host: string; status?: GitControlStatus }> {
-  return (await git()).post('git/pull', {
+}, client: PackageApi): Promise<{ ok: boolean; op: 'pull'; host: string; status?: GitControlStatus }> {
+  return client.post('git/pull', {
     source: params.source,
     ...repoBody(params.repo),
     ...(params.projectId ? { projectId: params.projectId } : {}),
@@ -811,8 +813,8 @@ export async function pushGit(params: {
   projectId?: string;
   source: string;
   repo?: string;
-}): Promise<{ ok: boolean; op: 'push'; host: string }> {
-  return (await git()).post('git/push', {
+}, client: PackageApi): Promise<{ ok: boolean; op: 'push'; host: string }> {
+  return client.post('git/push', {
     source: params.source,
     ...repoBody(params.repo),
     ...(params.projectId ? { projectId: params.projectId } : {}),
@@ -836,8 +838,8 @@ export async function searchFiles(params: {
   created_before?: string;
   include_siblings?: boolean;
   limit?: number;
-}): Promise<FSSearchResponse> {
-  return (await api()).post('search', params);
+}, client: PackageApi): Promise<FSSearchResponse> {
+  return client.post('search', params);
 }
 
 /**
@@ -855,14 +857,14 @@ export async function uploadFile(params: {
   file: File;
   uri?: string;
   tags?: string[];
-}): Promise<FSUploadResponse> {
+}, client: PackageApi): Promise<FSUploadResponse> {
   const form = new FormData();
   form.append('agentId', params.agentId);
   if (params.projectId) form.append('projectId', params.projectId);
   form.append('file', params.file);
   if (params.uri) form.append('uri', params.uri);
   if (params.tags?.length) form.append('tags', params.tags.join(','));
-  return (await api()).upload('upload', form);
+  return client.upload('upload', form);
 }
 
 /**
@@ -901,8 +903,9 @@ export type FSWriteRequest = {
 
 export async function writeFile(
   params: { agentId: string; projectId?: string } & FSWriteRequest,
+  client: PackageApi,
 ): Promise<FSWriteResponse> {
-  return (await api()).post('write', params);
+  return client.post('write', params);
 }
 
 /**
@@ -927,8 +930,8 @@ export async function approveFileReview(params: {
   uri?: string;
   expectedFingerprint?: string;
   acknowledgeCurrentState?: true;
-}): Promise<FSReviewApproveResponse> {
-  return (await api()).post('approve', params);
+}, client: PackageApi): Promise<FSReviewApproveResponse> {
+  return client.post('approve', params);
 }
 
 // ---------------------------------------------------------------------------
@@ -942,8 +945,8 @@ export async function approveFileReview(params: {
 export type { PendingChangeRecord, PendingPreview, PendingReviewIntent } from '@neuralis/brain-core/domain/pending-change';
 import type { PendingChangeRecord, PendingPreview } from '@neuralis/brain-core/domain/pending-change';
 
-export async function previewPendingChange(params: { agentId: string; projectId?: string; id: string }): Promise<PendingPreview> {
-  const result = await (await api()).post('pending', { ...params, action: 'preview' }) as { preview: PendingPreview };
+export async function previewPendingChange(params: { agentId: string; projectId?: string; id: string }, client: PackageApi): Promise<PendingPreview> {
+  const result = await client.post('pending', { ...params, action: 'preview' }) as { preview: PendingPreview };
   return result.preview;
 }
 
@@ -970,8 +973,9 @@ export type PendingChangesQuery = {
  */
 export async function listPendingChanges(
   params: PendingChangesQuery,
+  client: PackageApi,
 ): Promise<{ ok: boolean; changes: PendingChangeRecord[]; orphanIds: string[] }> {
-  const res = await (await api()).post('pending', params) as {
+  const res = await client.post('pending', params) as {
     ok?: boolean; changes?: PendingChangeRecord[]; orphanIds?: string[];
   };
   return {
@@ -985,10 +989,10 @@ export async function listPendingChanges(
  * The caller's visible pending COUNT — the list's own per-record floor, no orphan
  * probe and no rows on the wire. Feeds the Changes badge.
  */
-export async function countPendingChanges(params: { agentId: string; projectId?: string }): Promise<number> {
+export async function countPendingChanges(params: { agentId: string; projectId?: string }, client: PackageApi): Promise<number> {
   const qs: Record<string, string> = { agentId: params.agentId, count_only: '1' };
   if (params.projectId) qs.projectId = params.projectId;
-  const res = await (await api()).get('pending', qs) as { count?: number };
+  const res = await client.get('pending', qs) as { count?: number };
   return typeof res?.count === 'number' ? res.count : 0;
 }
 
@@ -998,8 +1002,8 @@ export async function revertPendingChange(params: {
   id: string;
   expectedFingerprint?: string;
   acknowledgeCurrentState?: true;
-}): Promise<{ ok: boolean; id: string; uri?: string; error?: string }> {
-  return (await api()).post('pending', { ...params, action: 'revert' }) as Promise<{ ok: boolean; id: string; uri?: string; error?: string }>;
+}, client: PackageApi): Promise<{ ok: boolean; id: string; uri?: string; error?: string }> {
+  return client.post('pending', { ...params, action: 'revert' }) as Promise<{ ok: boolean; id: string; uri?: string; error?: string }>;
 }
 
 /** Scan the caller's visible pending changes for ORPHANED rows — backing target
@@ -1009,8 +1013,8 @@ export async function scanOrphanedPending(params: {
   agentId: string;
   projectId?: string;
   conversationId?: string;
-}): Promise<{ ok: boolean; orphans: PendingChangeRecord[] }> {
-  const res = await (await api()).post('pending', { ...params, action: 'scan-orphans' }) as { ok?: boolean; orphans?: PendingChangeRecord[] };
+}, client: PackageApi): Promise<{ ok: boolean; orphans: PendingChangeRecord[] }> {
+  const res = await client.post('pending', { ...params, action: 'scan-orphans' }) as { ok?: boolean; orphans?: PendingChangeRecord[] };
   return { ok: res?.ok !== false, orphans: Array.isArray(res?.orphans) ? res.orphans : [] };
 }
 
@@ -1020,8 +1024,8 @@ export async function discardPendingChange(params: {
   agentId: string;
   projectId?: string;
   id: string;
-}): Promise<{ ok: boolean; id: string; uri?: string; error?: string }> {
-  return (await api()).post('pending', { ...params, action: 'discard' }) as Promise<{ ok: boolean; id: string; uri?: string; error?: string }>;
+}, client: PackageApi): Promise<{ ok: boolean; id: string; uri?: string; error?: string }> {
+  return client.post('pending', { ...params, action: 'discard' }) as Promise<{ ok: boolean; id: string; uri?: string; error?: string }>;
 }
 
 /** DISMISS ONE live-source pending record — the op-aware "accept-and-stop-
@@ -1034,8 +1038,8 @@ export async function dismissPendingChange(params: {
   id: string;
   expectedFingerprint?: string;
   acknowledgeCurrentState?: true;
-}): Promise<{ ok: boolean; id: string; uri?: string; error?: string; retryable?: boolean }> {
-  return (await api()).post('pending', { ...params, action: 'dismiss' }) as Promise<{ ok: boolean; id: string; uri?: string; error?: string; retryable?: boolean }>;
+}, client: PackageApi): Promise<{ ok: boolean; id: string; uri?: string; error?: string; retryable?: boolean }> {
+  return client.post('pending', { ...params, action: 'dismiss' }) as Promise<{ ok: boolean; id: string; uri?: string; error?: string; retryable?: boolean }>;
 }
 
 /** Bulk-discard every orphaned pending change the caller can write (the Repair
@@ -1044,8 +1048,8 @@ export async function discardOrphanedPending(params: {
   agentId: string;
   projectId?: string;
   conversationId?: string;
-}): Promise<{ ok: boolean; discarded: number }> {
-  const res = await (await api()).post('pending', { ...params, action: 'discard-orphans' }) as { ok?: boolean; discarded?: number };
+}, client: PackageApi): Promise<{ ok: boolean; discarded: number }> {
+  const res = await client.post('pending', { ...params, action: 'discard-orphans' }) as { ok?: boolean; discarded?: number };
   return { ok: res?.ok !== false, discarded: typeof res?.discarded === 'number' ? res.discarded : 0 };
 }
 
@@ -1066,16 +1070,16 @@ export function getRawFileUrl(agentId: string, uri: string, projectId?: string):
 export async function checkVectorHealth(params: {
   agentId: string;
   projectId?: string;
-}): Promise<Record<string, unknown>> {
-  return (await api()).post('health', params);
+}, client: PackageApi): Promise<Record<string, unknown>> {
+  return client.post('health', params);
 }
 
 /** Expensive integrity scan (orphan + duplicate detection) — explicit only. */
 export async function scanVectorHealth(params: {
   agentId: string;
   projectId?: string;
-}): Promise<{ orphanChunkCount?: number; duplicateGroups?: number; generatedAt?: string }> {
-  return (await api()).post('health/scan', params);
+}, client: PackageApi): Promise<{ orphanChunkCount?: number; duplicateGroups?: number; generatedAt?: string }> {
+  return client.post('health/scan', params);
 }
 
 export async function runHealthAction(params: {
@@ -1084,12 +1088,12 @@ export async function runHealthAction(params: {
   action: 'gc' | 'repair-orphans' | 'deduplicate' | 'repair-pending';
   dryRun?: boolean;
   retentionHours?: number;
-}): Promise<Record<string, unknown>> {
-  return (await api()).post('health/gc', params);
+}, client: PackageApi): Promise<Record<string, unknown>> {
+  return client.post('health/gc', params);
 }
 
-export async function createSource(params: CreateSourceRequest): Promise<SourceConfigRecord> {
-  return (await api()).post('sources', params);
+export async function createSource(params: CreateSourceRequest, client: PackageApi): Promise<SourceConfigRecord> {
+  return client.post('sources', params);
 }
 
 export async function deleteSource(params: {
@@ -1101,19 +1105,19 @@ export async function deleteSource(params: {
    *  false/omitted, only the config and in-memory connector binding are
    *  removed; vectors stay in Qdrant. */
   purgeVectors?: boolean;
-}): Promise<{ ok: true; purgeJob?: SyncJobSnapshotRecord }> {
+}, client: PackageApi): Promise<{ ok: true; purgeJob?: SyncJobSnapshotRecord }> {
   const qs = new URLSearchParams({ agentId: params.agentId });
   if (params.projectId) qs.set('projectId', params.projectId);
   if (params.purgeVectors) qs.set('purge', '1');
-  return (await api()).del(`sources/${encodeURIComponent(params.source)}?${qs.toString()}`);
+  return client.del(`sources/${encodeURIComponent(params.source)}?${qs.toString()}`);
 }
 
 export async function resetSync(params: {
   agentId: string;
   projectId?: string;
   source: string;
-}): Promise<{ ok: true; source: string }> {
-  return (await api()).post('sources/reset', params);
+}, client: PackageApi): Promise<{ ok: true; source: string }> {
+  return client.post('sources/reset', params);
 }
 
 /**
@@ -1124,8 +1128,8 @@ export async function reindexSource(params: {
   agentId: string;
   projectId?: string;
   source: string;
-}): Promise<SyncJobSnapshotRecord> {
-  return (await api()).post('sources/reindex', params);
+}, client: PackageApi): Promise<SyncJobSnapshotRecord> {
+  return client.post('sources/reindex', params);
 }
 
 export type IndexPurgeCounts = { removedParents: number; removedChunks: number; retained: number; unresolved: number; canMaintain: boolean };
@@ -1133,8 +1137,8 @@ export type IndexPurgeSelector = { kind: 'source' } | { kind: 'folder' | 'file';
 export async function purgeSourceIndex(params: {
   agentId: string; projectId?: string; source: string;
   selector: IndexPurgeSelector; mode: 'estimate' | 'apply'; obsoleteOnly?: boolean;
-}): Promise<IndexPurgeCounts> {
-  return (await api()).post('sources/purge', params);
+}, client: PackageApi): Promise<IndexPurgeCounts> {
+  return client.post('sources/purge', params);
 }
 
 /** The scope of a forced re-embed: the whole source, one `folder`, or one `uri` (full URIs). */
@@ -1191,12 +1195,20 @@ function normalizeReembedEstimate(raw: unknown): ReembedEstimate | null {
 }
 
 /**
- * Estimate a forced re-embed of the scope. The route answers BEFORE it touches
- * the queue or the source's sync markers — an estimate has no side effect.
+ * `reembed` = every file in scope again (`force`); `pending` = only the files
+ * whose semantic embedding is missing or stale (`embeddingOnly`, the debt pass).
+ */
+export type ReembedKind = 'reembed' | 'pending';
+const reembedVerb = (kind: ReembedKind) => (kind === 'pending' ? { embeddingOnly: true } : { force: true });
+
+/**
+ * Estimate the scope. The route answers BEFORE it touches the queue or the
+ * source's sync markers — an estimate has no side effect. For `pending` the
+ * figures are an upper bound: the whole scope, of which only the owed part runs.
  */
-export async function estimateReembed(params: ReembedScope): Promise<ReembedEstimate | null> {
+export async function estimateReembed(params: ReembedScope, kind: ReembedKind, client: PackageApi): Promise<ReembedEstimate | null> {
   return normalizeReembedEstimate(
-    await (await api()).post<unknown>('sources/reindex', { ...params, force: true, estimate: true }),
+    await client.post<unknown>('sources/reindex', { ...params, ...reembedVerb(kind), estimate: true }),
   );
 }
 
@@ -1207,8 +1219,10 @@ export async function estimateReembed(params: ReembedScope): Promise<ReembedEsti
  */
 export async function startReembed(
   params: ReembedScope,
+  kind: ReembedKind,
+  client: PackageApi,
 ): Promise<{ documents: number | null; truncated: boolean; job: SyncJobSnapshotRecord | null }> {
-  const raw = await (await api()).post<Record<string, unknown> | null>('sources/reindex', { ...params, force: true });
+  const raw = await client.post<Record<string, unknown> | null>('sources/reindex', { ...params, ...reembedVerb(kind) });
   const job = raw?.job && typeof raw.job === 'object' ? (raw.job as SyncJobSnapshotRecord) : null;
   return { documents: finiteOrNull(raw?.documents), truncated: raw?.truncated === true, job };
 }
@@ -1221,14 +1235,14 @@ export async function cancelSync(params: {
   agentId: string;
   projectId?: string;
   source?: string;
-}): Promise<{ ok: true; source?: string; cancelled: boolean | number }> {
-  return (await api()).post('sources/cancel', params);
+}, client: PackageApi): Promise<{ ok: true; source?: string; cancelled: boolean | number }> {
+  return client.post('sources/cancel', params);
 }
 
 export async function getSourcesHealth(params: {
   agentId: string;
   projectId?: string;
-}): Promise<Array<{
+}, client: PackageApi): Promise<Array<{
   source: string;
   source_kind: string;
   sync_status: string;
@@ -1236,7 +1250,7 @@ export async function getSourcesHealth(params: {
 }>> {
   const qs: Record<string, string> = { agentId: params.agentId };
   if (params.projectId) qs.projectId = params.projectId;
-  return (await api()).get('sources/health', qs);
+  return client.get('sources/health', qs);
 }
 
 /**
@@ -1253,10 +1267,10 @@ export async function browseDirectories(params: {
   path: string;
   agentId: string;
   projectId?: string;
-}): Promise<{ entries: Array<{ name: string; path: string; type: 'directory' }> }> {
+}, client: PackageApi): Promise<{ entries: Array<{ name: string; path: string; type: 'directory' }> }> {
   const qs: Record<string, string> = { path: params.path, agentId: params.agentId };
   if (params.projectId) qs.projectId = params.projectId;
-  return (await api()).get('sources/browse', qs);
+  return client.get('sources/browse', qs);
 }
 
 export type SourceKindRecord = {
@@ -1287,10 +1301,10 @@ export type SourceKindSchema = {
   defaultSyncExcludes?: string[];
 };
 
-export async function listSourceKinds(): Promise<{ kinds: SourceKindRecord[] }> {
-  return (await api()).get('sources/kinds', {});
+export async function listSourceKinds(client: PackageApi): Promise<{ kinds: SourceKindRecord[] }> {
+  return client.get('sources/kinds', {});
 }
 
-export async function getSourceKindSchema(kind: string): Promise<SourceKindSchema> {
-  return (await api()).get(`sources/kinds/${encodeURIComponent(kind)}/schema`, {});
+export async function getSourceKindSchema(kind: string, client: PackageApi): Promise<SourceKindSchema> {
+  return client.get(`sources/kinds/${encodeURIComponent(kind)}/schema`, {});
 }