Official

files

Built-in files UI (JavaScript UI plugin).

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/files@0.2.3

Permissions in 0.2.3

  • Read files fs.readMediumReads files in the listed places.List the files of the workspacePlaces: the open workspace
  • Read chats chats.readMediumReads your transcripts and chat lists.Refresh the file list when an agent finishes a turn
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Show the files button and panelSlots: railright

Files

controller.ts6.1 KB
// Scoped file-panel effects: host reads and the divergence/tabs client.
// A layer owns one state instance for both registered views.
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Stream from "effect/Stream";
import { App, Host, Notify, Services } from "divergence/effect";
import type { EffectClient } from "divergence/effect";
import type { AppState, ViewHandle } from "divergence";
import type { Tabs } from "../tabs/contract.ts";
import { initialState } from "./panel.ts";

const makeFiles = Effect.fn("Files.make")(function* () {
  const host = yield* Host;
  const app = yield* App;
  const notify = yield* Notify;
  const services = yield* Services;
  const scope = yield* Effect.scope;
  const state = initialState();
  const views: ViewHandle[] = [];
  const redraw = () => {
    for (const view of views) view.update();
  };
  const warn = (error: { message: string }) => notify.warning(`Files unavailable: ${error.message}`);
  // One folder's names. A host before `path` answers every path without
  // `folders`: the panel then draws that whole list instead.
  const list = Effect.fn("Files.list")(function* (workspaceId: string, folder: string) {
    const result = yield* host.call("host/fs.search", { workspaceId, limit: 100000, depth: 1, path: folder });
    if (state.workspaceId !== workspaceId) return;
    if (result.folders)
      state.listing = { ...state.listing, [folder]: { files: result.paths, folders: result.folders } };
    else state.all = result.paths;
    redraw();
  });
  // Lists the top and every folder listed before, at once. A new workspace
  // starts from its top.
  const refresh = Effect.fn("Files.refresh")(function* (workspaceId: string) {
    if (workspaceId !== state.workspaceId) {
      state.workspaceId = workspaceId;
      state.listing = {};
      state.all = null;
      state.results = [];
    }
    const folders = state.all ? [""] : ["", ...Object.keys(state.listing).filter((key) => key)];
    yield* Effect.forEach(folders, (folder) => list(workspaceId, folder), {
      concurrency: "unbounded",
      discard: true,
    }).pipe(Effect.catchTag(["HostCallFailed", "NeedsReview", "PermissionNotGranted"], warn));
  });
  const expand = Effect.fn("Files.expand")(function* (workspaceId: string, folder: string) {
    if (state.all || state.listing[folder]) return;
    yield* list(workspaceId, folder).pipe(
      Effect.catchTag(["HostCallFailed", "NeedsReview", "PermissionNotGranted"], warn),
    );
  });
  // The host searches every path; a reply for an older query is dropped.
  const search = Effect.fn("Files.search")(function* (workspaceId: string, query: string) {
    const q = query.trim();
    if (!q) return;
    const result = yield* host
      .call("host/fs.search", { workspaceId, query: q, limit: 500 })
      .pipe(
        Effect.catchTag(["HostCallFailed", "NeedsReview", "PermissionNotGranted"], (error) =>
          Effect.as(warn(error), null),
        ),
      );
    if (!result || state.workspaceId !== workspaceId || state.query.trim() !== q) return;
    state.results = result.paths;
    redraw();
  });
  const followApp = Effect.fn("Files.followApp")(function* (next: AppState) {
    if (next.workspaceId && next.workspaceId !== state.workspaceId) yield* refresh(next.workspaceId);
  });
  const openFile = Effect.fn("Files.openFile")(function* (workspaceId: string, path: string) {
    const client = state.tabs;
    // Without the tabs plugin there is no detail pane; the shared request
    // the baseline wrote would have had no reader either.
    if (!client) return;
    // The file the user picked takes the keyboard. Left on the list, it
    // kept the rail's fly-out open after the pointer had gone.
    yield* client.open({ kind: "file", workspaceId, path, focus: true }).pipe(
      // A call that loses its provider on the way behaves like no reader.
      Effect.ignore,
    );
  });
  const toggle = Effect.fn("Files.toggle")((next: AppState) =>
    app.update({
      shared: {
        rightPanel: next.shared?.rightPanel === "files" ? null : "files",
      },
    }),
  );
  // The open file follows the visible tab while the tabs plugin runs. One
  // episode per provider: the previous follow ends when the provider goes.
  const followTabs = Effect.fn("Files.followTabs")(function* () {
    yield* services.when<typeof Tabs>("divergence/tabs").pipe(
      Stream.runForEach((option) =>
        Effect.gen(function* () {
          if (state.follow) {
            yield* Fiber.interrupt(state.follow);
            state.follow = undefined;
          }
          if (Option.isNone(option)) {
            state.tabs = undefined;
            return;
          }
          const client: EffectClient<typeof Tabs> = option.value;
          state.tabs = client;
          const shown = (tab: { kind: string; path: string } | null) => {
            state.activePath = tab?.kind === "file" ? tab.path : null;
          };
          state.follow = yield* Effect.forkIn(
            client.on("activeChanged").pipe(
              Stream.runForEach((tab) =>
                Effect.sync(() => {
                  shown(tab);
                  for (const view of views) view.update();
                }),
              ),
            ),
            scope,
            { startImmediately: true },
          );
          yield* client.active({}).pipe(
            Effect.tap((tab) =>
              Effect.sync(() => {
                shown(tab);
                for (const view of views) view.update();
              }),
            ),
            // A provider that goes away mid-read leaves the last selection.
            Effect.ignore,
          );
        }),
      ),
      Effect.forkIn(scope, { startImmediately: true }),
    );
  });
  yield* followTabs();
  return {
    state,
    views,
    refresh,
    expand,
    search,
    followApp,
    openFile,
    toggle,
    close: app.update({ shared: { rightPanel: null } }),
  };
});

export class Files extends Context.Service<Files, Effect.Success<ReturnType<typeof makeFiles>>>()("files/Files") {
  static readonly layer = Layer.effect(Files, makeFiles());
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.6latestNov 21, 2026>=5 <613.7 KB3 permissionsListed
0.2.5Nov 11, 2026>=5 <613.3 KB3 permissionsListed
0.2.4Nov 9, 2026>=5 <612.3 KB3 permissionsListed
0.2.3Oct 27, 2026>=2 <48 KB3 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.