@nyte-ai/plugin 0.0.0-stage → 0.0.19

package/dist/src/client/mount.js

@@ -0,0 +1,252 @@
+// src/client/mount.ts
+function derives(entry) {
+  return typeof entry === "function";
+}
+function registry(key, siblings) {
+  const items = new Set;
+  const derivations = new Set;
+  function add(entry) {
+    if (derives(entry)) {
+      derivations.add(entry);
+      return () => void derivations.delete(entry);
+    }
+    items.add(entry);
+    return () => void items.delete(entry);
+  }
+  return {
+    add,
+    list() {
+      const draft = new Map([...items].map((item) => [key(item), item]));
+      for (const derive of derivations)
+        derive({
+          set: (id, item) => void draft.set(id, item),
+          get: (id) => draft.get(id),
+          delete: (id) => void draft.delete(id),
+          ids: () => [...draft.keys()],
+          wrap: (id, wrap) => {
+            const inner = draft.get(id);
+            if (inner !== undefined)
+              draft.set(id, wrap(inner));
+          }
+        }, siblings());
+      return [...draft.values()];
+    }
+  };
+}
+function settingsRegistry(siblings) {
+  const base = registry((item) => item.id, siblings);
+  const values = new Map;
+  const listeners = new Map;
+  const current = (id) => {
+    const definition = base.list().find((item) => item.id === id);
+    if (definition === undefined)
+      throw new Error(`No setting is declared with id ${id}.`);
+    return values.has(id) ? values.get(id) : definition.default;
+  };
+  async function* watch(id) {
+    let pending = Promise.withResolvers();
+    const listener = (value) => pending.resolve(value);
+    const set = listeners.get(id) ?? new Set;
+    set.add(listener);
+    listeners.set(id, set);
+    try {
+      yield current(id);
+      for (;; ) {
+        const value = await pending.promise;
+        pending = Promise.withResolvers();
+        yield value;
+      }
+    } finally {
+      set.delete(listener);
+    }
+  }
+  function add(entry) {
+    if (derives(entry))
+      return base.add(entry);
+    const remove = base.add(entry);
+    return Object.assign(remove, {
+      get: async () => current(entry.id),
+      set: async (value) => {
+        values.set(entry.id, value);
+        for (const listener of listeners.get(entry.id) ?? [])
+          listener(value);
+      },
+      watch: () => watch(entry.id)
+    });
+  }
+  return { add, list: () => base.list(), value: async (id) => current(id), watch };
+}
+function memoryStorage(client) {
+  const values = new Map;
+  async function get(key) {
+    return values.get(key);
+  }
+  const storage = {
+    get,
+    set: async (key, value) => void values.set(key, value),
+    delete: async (key) => void values.delete(key),
+    keys: async () => [...values.keys()],
+    at: () => storage,
+    secrets: {
+      get: async () => {
+        return;
+      },
+      set: async () => {
+        throw new Error(`The ${client} client keeps no plugin secrets.`);
+      },
+      delete: async () => {
+        return;
+      }
+    }
+  };
+  return storage;
+}
+function causeMessage(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+async function mountClientPlugins(options) {
+  const handlers = {
+    run_ended_anywhere: [],
+    app_ready: [],
+    session_opened: [],
+    before_submit: [],
+    session_closed: [],
+    app_closing: []
+  };
+  const controller = new AbortController;
+  const apis = [];
+  const register = (api, name, entry) => {
+    const handler = "run" in entry ? { order: entry.order ?? 0, run: entry.run, api } : { order: 0, run: entry, api };
+    const list = handlers[name];
+    list.push(handler);
+    list.sort((left, right) => left.order - right.order);
+    return () => {
+      const index = list.findIndex((candidate) => candidate === handler);
+      if (index !== -1)
+        list.splice(index, 1);
+    };
+  };
+  const context = (api, session, run) => ({
+    api,
+    signal: AbortSignal.any([controller.signal, AbortSignal.timeout(5000)]),
+    session,
+    head: null,
+    run
+  });
+  const reportFrom = (api, cause) => options.report(apis.find((entry) => entry.api === api)?.plugin.id ?? "plugin", causeMessage(cause));
+  const observe = async (list, event, session, run = null) => {
+    for (const handler of list) {
+      try {
+        await handler.run(event, context(handler.api, session, run));
+      } catch (cause) {
+        reportFrom(handler.api, cause);
+      }
+    }
+  };
+  for (const plugin of options.plugins) {
+    const registries = {
+      commands: registry((item) => item.name, () => registries),
+      settings: settingsRegistry(() => registries),
+      renderers: registry((item) => `${item.kind.kind}:${item.framework}`, () => registries),
+      keybindings: registry((item) => item.key, () => registries)
+    };
+    for (const command of plugin.contribute?.commands ?? [])
+      registries.commands.add(command);
+    for (const setting of plugin.contribute?.settings ?? [])
+      registries.settings.add(setting);
+    for (const renderer of plugin.contribute?.renderers ?? [])
+      registries.renderers.add(renderer);
+    for (const binding of plugin.contribute?.keybindings ?? [])
+      registries.keybindings.add(binding);
+    const api = {
+      side: "client",
+      sdk: options.connection,
+      contribute: registries,
+      storage: memoryStorage(options.client.name),
+      signal: controller.signal,
+      hook: (name, entry) => register(api, name, entry),
+      report: (issue) => options.report(plugin.id, issue.message),
+      reload: () => {
+        return;
+      },
+      client: options.client,
+      get session() {
+        return options.session();
+      },
+      ui: { notify: options.notify }
+    };
+    const hooks = plugin.hooks ?? {};
+    if (hooks.run_ended_anywhere !== undefined)
+      register(api, "run_ended_anywhere", hooks.run_ended_anywhere);
+    if (hooks.app_ready !== undefined)
+      register(api, "app_ready", hooks.app_ready);
+    if (hooks.session_opened !== undefined)
+      register(api, "session_opened", hooks.session_opened);
+    if (hooks.before_submit !== undefined)
+      register(api, "before_submit", hooks.before_submit);
+    if (hooks.session_closed !== undefined)
+      register(api, "session_closed", hooks.session_closed);
+    if (hooks.app_closing !== undefined)
+      register(api, "app_closing", hooks.app_closing);
+    apis.push({ plugin, api });
+  }
+  await Promise.all(apis.map(async ({ plugin, api }) => {
+    try {
+      await plugin.activate?.(api);
+    } catch (cause) {
+      options.report(plugin.id, causeMessage(cause));
+    }
+  }));
+  const renderers = new Map;
+  for (const { api } of apis)
+    for (const renderer of api.contribute.renderers.list())
+      if (options.client.frameworks.includes(renderer.framework) && !renderers.has(renderer.kind.kind))
+        renderers.set(renderer.kind.kind, renderer);
+  const ends = new Map;
+  let seeded = false;
+  await observe(handlers.app_ready, { restored: false }, null);
+  return {
+    ids: apis.map(({ plugin }) => plugin.id),
+    draw(session, message, placement) {
+      const renderer = renderers.get(message.partKind);
+      if (renderer === undefined)
+        return;
+      const part = session.part(message.part);
+      return renderer.render({ state: message.state, version: message.version, placement }, (action, input) => part.act(action, input));
+    },
+    sessionsChanged(sessions) {
+      for (const info of sessions) {
+        for (const head of info.heads) {
+          const key = `${info.id}/${head.name}`;
+          const last = head.execution.kind === "idle" ? head.execution.lastRun : null;
+          if (last === null || ends.get(key) === last.id)
+            continue;
+          ends.set(key, last.id);
+          if (seeded)
+            observe(handlers.run_ended_anywhere, { session: info.id, run: last.id, end: last.end }, info.id, last.id);
+        }
+      }
+      seeded = true;
+    },
+    async switched(previous, next) {
+      if (previous !== null)
+        await observe(handlers.session_closed, { session: previous }, previous.id);
+      await observe(handlers.session_opened, { session: next }, next.id);
+    },
+    async beforeSubmit(draft) {
+      for (const handler of handlers.before_submit) {
+        const decision = await handler.run(draft, context(handler.api, draft.session, null));
+        if (decision.action !== "continue")
+          return decision;
+      }
+      return { action: "continue" };
+    },
+    async dispose() {
+      await observe(handlers.app_closing, undefined, null);
+      controller.abort();
+    }
+  };
+}
+export {
+  mountClientPlugins
+};

package/dist/src/client/notifications.d.ts

@@ -0,0 +1,36 @@
+import type { RunEnd } from "@nyte-ai/schema";
+/**
+ * Tells the user when a run ends in any session this client can see:
+ * finished, or failed with the reason. A stopped run stays quiet because
+ * someone asked for it, and so do sessions a parent spawned, so a delegation
+ * does not ring once per child.
+ *
+ * @category plugins
+ * @since 0.1.0
+ */
+declare const _default: {
+    id: string;
+    hooks: {
+        run_ended_anywhere: (event: Readonly<{
+            readonly session: import("@nyte-ai/schema").SessionId;
+            readonly run: import("@nyte-ai/schema").RunId;
+            readonly end: RunEnd;
+        }>, { api }: {
+            readonly api: {
+                readonly side: "client";
+                readonly sdk: import("@nyte-ai/core").Connection;
+                readonly contribute: import("@nyte-ai/core").Registries<"client">;
+                readonly storage: import("@nyte-ai/core").PluginStorage;
+                readonly signal: AbortSignal;
+                hook<N extends "run_ended_anywhere" | "app_ready" | "session_opened" | "before_submit" | "session_closed" | "app_closing">(name: N, entry: import("@nyte-ai/core").HookEntry<"client", N>): import("@nyte-ai/schema").Disposer;
+                report(issue: import("@nyte-ai/schema").ValidationIssue): void;
+                reload(): void;
+            } & import("@nyte-ai/plugin/client").ClientApi;
+            readonly signal: AbortSignal;
+            readonly session: import("@nyte-ai/schema").SessionId | null;
+            readonly head: import("@nyte-ai/schema").HeadName | null;
+            readonly run: import("@nyte-ai/schema").RunId | null;
+        }) => Promise<void>;
+    };
+};
+export default _default;

package/dist/src/client/notifications.js

@@ -0,0 +1,24 @@
+// src/client/notifications.ts
+var notifications_default = {
+  id: "notifications",
+  hooks: {
+    run_ended_anywhere: async (event, { api }) => {
+      const info = await api.sdk.session(event.session).info();
+      if (info.parent !== null)
+        return;
+      const title = info.name ?? undefined;
+      const { end } = event;
+      if (end.kind === "completed")
+        api.ui.notify({ title, message: "Run finished", level: "info" });
+      else if (end.kind === "failed")
+        api.ui.notify({ title, message: `Run failed: ${line(end)}`, level: "error" });
+    }
+  }
+};
+function line(end) {
+  const text = end.failure.message.replace(/\s+/g, " ").trim();
+  return text.length > 120 ? `${text.slice(0, 119)}…` : text;
+}
+export {
+  notifications_default as default
+};

package/dist/src/client/presentation.d.ts

@@ -0,0 +1,362 @@
+import { text, thinking } from "@nyte-ai/core";
+import type { PartState } from "@nyte-ai/core";
+import type { Execution, Failure, HeadInfo, Message, MessageSource, SessionInfo, ToolClass, ToolPartState, UserContent, UserStatus } from "@nyte-ai/schema";
+/**
+ * A message the user sent, or one a child, job or action delivered for them.
+ *
+ * @category presentation
+ */
+export type UserMessage = Extract<Message, {
+    readonly kind: "user";
+}>;
+/**
+ * A message that carries a part: text, thinking, a tool call or a plugin's part.
+ *
+ * @category presentation
+ */
+export type PartMessage = Extract<Message, {
+    readonly kind: "part";
+}>;
+/**
+ * A part message holding a tool call.
+ *
+ * @category presentation
+ */
+export type ToolMessage = PartMessage & {
+    readonly state: ToolPartState;
+};
+/**
+ * A part message holding assistant text.
+ *
+ * @category presentation
+ */
+export type TextMessage = PartMessage & {
+    readonly state: PartState<typeof text>;
+};
+/**
+ * A part message holding the model's thinking.
+ *
+ * @category presentation
+ */
+export type ThinkingMessage = PartMessage & {
+    readonly state: PartState<typeof thinking>;
+};
+/**
+ * A user message a child session or background job delivered as its report.
+ *
+ * @category presentation
+ */
+export type ReportMessage = UserMessage & {
+    readonly source: Extract<MessageSource, {
+        readonly kind: "child" | "job";
+    }>;
+};
+/**
+ * Narrows to a tool call's part.
+ *
+ * @category presentation
+ */
+export declare function showsTool(message: Message): message is ToolMessage;
+/**
+ * Narrows to an assistant text part.
+ *
+ * @category presentation
+ */
+export declare function showsText(message: Message): message is TextMessage;
+/**
+ * Narrows to a thinking part.
+ *
+ * @category presentation
+ */
+export declare function showsThinking(message: Message): message is ThinkingMessage;
+/**
+ * A part a client has no renderer for, shown raw: the text its state carries
+ * as `markdown` or `text`, else its state as indented JSON.
+ *
+ * @category presentation
+ */
+export type RawPart = {
+    readonly format: "text" | "json";
+    readonly body: string;
+};
+/**
+ * Reads a part's state raw, for a part kind or state shape this client does
+ * not know, such as one a newer host or an absent plugin sent.
+ *
+ * @category presentation
+ */
+export declare function readRawPart(message: PartMessage): RawPart;
+/**
+ * Narrows to the report a child or job delivered; a person or an action sent the rest.
+ *
+ * @category presentation
+ */
+export declare function showsReport(message: UserMessage): message is ReportMessage;
+type PendingStatus = Extract<UserStatus, {
+    readonly kind: "pending";
+}>;
+/**
+ * A message that waits in the queue: unsent, or pending for a later turn. A pending steer sent
+ * while idle or joining the live run is never one.
+ *
+ * @category presentation
+ */
+export type QueuedMessage = UserMessage & {
+    readonly status: Extract<UserStatus, {
+        readonly kind: "unsent";
+    }> | (PendingStatus & {
+        readonly schedule: Exclude<PendingStatus["schedule"], {
+            readonly kind: "joined";
+        }>;
+    });
+};
+/**
+ * Whether a message waits in the queue rather than showing in the transcript. A retrying send
+ * always waits. Reports, joined steers and steers sent while idle stay in the transcript.
+ * Other messages wait only while a run is active.
+ *
+ * @category presentation
+ */
+export declare function waitsInQueue(message: UserMessage, running: boolean): message is QueuedMessage;
+/**
+ * What a user message shows: an action's label in place of the prompt it sent.
+ *
+ * @category presentation
+ */
+export declare function shownContent(message: UserMessage): UserContent;
+/**
+ * The tense a tool line speaks in: running, done, or none when the call did
+ * not finish and no verb would be true.
+ *
+ * @category presentation
+ */
+export type ToolTense = "running" | "past" | "none";
+/**
+ * The colour family of a tool line's state.
+ *
+ * @category presentation
+ */
+export type ToolTone = "running" | "attention" | "success" | "failure" | "stopped";
+/**
+ * The word a tool line adds after its subject when the outcome needs saying.
+ *
+ * @category presentation
+ */
+export type ToolWord = "Needs input" | "Failed" | "Blocked" | "Stopped" | "Interrupted";
+/**
+ * How every client shows a tool call's state; clients change only case and glyphs.
+ *
+ * @category presentation
+ */
+export interface ToolStatus {
+    readonly tense: ToolTense;
+    readonly tone: ToolTone;
+    readonly word: ToolWord | undefined;
+}
+/**
+ * A settled call reads its outcome. An open call whose run failed was cut off,
+ * not failed by the tool: the user's stop reads "Stopped", anything else
+ * "Interrupted", and the turn's failure notice says why.
+ *
+ * @category presentation
+ */
+export declare function toolStatus(message: Pick<ToolMessage, "state" | "status">): ToolStatus;
+/**
+ * A settled call's text: its text content, failure message or rejection reason.
+ *
+ * @category presentation
+ */
+export declare function toolOutput(state: ToolPartState): string;
+/**
+ * The mark a session list draws for a head's execution.
+ *
+ * @category presentation
+ */
+export type SessionMark = "waiting" | "retry" | "working" | "failed" | "idle";
+/**
+ * The mark for an execution; a session without one is idle.
+ *
+ * @category presentation
+ */
+export declare function executionMark(execution: Execution | undefined): SessionMark;
+/**
+ * The head a session row speaks for: `main`, else the first.
+ *
+ * @category presentation
+ */
+export declare function mainHead(session: Pick<SessionInfo, "heads">): HeadInfo | undefined;
+/**
+ * The mark for a session's main head.
+ *
+ * @category presentation
+ */
+export declare function sessionMark(session: Pick<SessionInfo, "heads">): SessionMark;
+/**
+ * The text after a one-line draft's leading `/name `, while the caret is past
+ * it: `start` is where that text begins, `query` runs from there to the caret.
+ *
+ * @category presentation
+ */
+export interface CommandArgument {
+    readonly command: string;
+    readonly start: number;
+    readonly query: string;
+}
+/**
+ * Finds the text a draft gives the command it starts with, or undefined when
+ * it starts with none, spans lines, or the caret is before that text.
+ *
+ * @category presentation
+ */
+export declare function findCommandArgument(value: string, cursor: number): CommandArgument | undefined;
+/**
+ * The `@` mention or `/` command the caret is in, with the word's bounds.
+ *
+ * @category presentation
+ */
+export interface CompletionTrigger {
+    readonly kind: "@" | "/";
+    readonly start: number;
+    readonly end: number;
+    readonly query: string;
+}
+/**
+ * Finds the completion trigger around the caret, or undefined outside one.
+ *
+ * @category presentation
+ */
+export declare function completionTrigger(value: string, cursor?: number): CompletionTrigger | undefined;
+/**
+ * The verb for each tense that asserts one.
+ *
+ * @category presentation
+ */
+export type ToolVerbs = Readonly<Record<Exclude<ToolTense, "none">, string>>;
+type DelegateClass = Extract<ToolClass, {
+    readonly kind: "delegate";
+}>;
+/**
+ * How a custom tool reads: its verbs, and the name and server an MCP tool
+ * carries, or a fixed detail for a built-in.
+ *
+ * @category presentation
+ */
+export interface CustomTool {
+    readonly verbs: ToolVerbs;
+    readonly name?: string;
+    readonly server?: string;
+    readonly detail?: string;
+}
+/**
+ * Reads a custom tool's label: a built-in's own words, an MCP tool's name and
+ * server, a phrase used as its own verb, or a bare name that "Ran".
+ *
+ * @category presentation
+ */
+export declare function customTool(label: string): CustomTool;
+/**
+ * The verbs a tool call speaks with.
+ *
+ * @category presentation
+ */
+export declare function toolVerbs(toolClass: ToolClass): ToolVerbs;
+/**
+ * What a verbless line adds after its subject so the tool stays named: a path
+ * alone does not say read from edit. A command or a custom tool needs nothing.
+ *
+ * @category presentation
+ */
+export declare function toolNoun(toolClass: ToolClass): string | undefined;
+/**
+ * The agent a delegate call names, "subagent" when the call gave no title.
+ *
+ * @category presentation
+ */
+export declare function delegateSubject(toolClass: DelegateClass): string;
+/**
+ * What a call acts on, in full: a path, a command, an agent's title, or a
+ * custom tool's name.
+ *
+ * @category presentation
+ */
+export declare function toolSubject(toolClass: ToolClass): string | undefined;
+/**
+ * One line naming a call: the tense's verb before the subject, or the subject
+ * and its noun when no verb is true. A custom tool without a name reads as its label.
+ *
+ * @category presentation
+ */
+export declare function toolTitle(toolClass: ToolClass, tense: ToolTense, subject?: string | undefined): string;
+/**
+ * A path relative to the working directory when it lies inside it.
+ *
+ * @category presentation
+ */
+export declare function tidyPath(path: string, cwd: string | undefined): string;
+/**
+ * The last segment of a path; the working directory reads as its own name.
+ *
+ * @category presentation
+ */
+export declare function placeName(path: string, cwd: string | undefined): string;
+/**
+ * A command on one line, without a leading `cd` into the working directory.
+ *
+ * @category presentation
+ */
+export declare function condensedCommand(command: string, cwd: string | undefined): string;
+/**
+ * An elapsed time as a tool or turn shows it: 4.2s, 42s, 5m 3s, 1h 12m. A
+ * negative span reads as zero.
+ *
+ * @category presentation
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * A span in whole seconds, as a settled turn's thinking or a retry countdown
+ * shows it: 42s, 5m, 5m 3s, 1h, 1h 12m. A negative span reads as zero.
+ *
+ * @category presentation
+ */
+export declare function formatWholeDuration(ms: number): string;
+/**
+ * A subject short enough for a narrow line, with the full one as `title`
+ * when they differ.
+ *
+ * @category presentation
+ */
+export interface ToolDetail {
+    readonly text: string;
+    readonly title?: string;
+}
+/**
+ * The compact subject of a call, relative to the working directory.
+ *
+ * @category presentation
+ */
+export declare function toolDetail(toolClass: ToolClass, cwd: string | undefined): ToolDetail | undefined;
+/**
+ * The step that gets a failed run going again. Each client names it its own
+ * way: a command, a key or a settings page.
+ *
+ * @category presentation
+ */
+export type Recovery = "compact" | "sign-in" | "switch-model";
+/**
+ * What a failed run says: one sentence, its tone, and the step that recovers
+ * from it when the user has one to take.
+ *
+ * @category presentation
+ */
+export interface FailureNotice {
+    readonly text: string;
+    readonly tone: "neutral" | "danger";
+    readonly recovery: Recovery | undefined;
+}
+/**
+ * The notice for a run's failure.
+ *
+ * @category presentation
+ */
+export declare function failureNotice(failure: Failure): FailureNotice;
+export {};