@neosh/api 0.1.0 → 0.3.0

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@neosh/api",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The neosh plugin API. Types are generated from the Rust side and drift-checked in CI.",
   "license": "MIT",
   "type": "module",
   "types": "src/index.ts",
-  "exports": { ".": "./src/index.ts" },
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "keywords": [
     "neosh",
     "neosh-plugin",

package/src/generated/ApiCall.ts

@@ -366,6 +366,7 @@ export type ApiCall =
   | { "call": "swarm_probe"; addr: string }
   | { "call": "swarm_pair"; node: NodeId; name: string; addr?: string | null }
   | { "call": "swarm_unpair"; node: NodeId }
+  | { "call": "swarm_rename"; node: NodeId; name?: string | null }
   | { "call": "swarm_reconnect"; node: NodeId }
   | { "call": "swarm_disconnect"; node: NodeId }
   | { "call": "swarm_strangers" }
@@ -517,4 +518,20 @@ export type ApiCall =
      * conversation is about the workspace, and is never on screen by definition.
      */
     session?: SessionId | null;
+  }
+  | {
+    "call": "update_check";
+    /**
+     * Ask the network again rather than answering from the last check.
+     */
+    force: boolean;
+  }
+  | { "call": "update_apply" }
+  | {
+    "call": "update_restart";
+    /**
+     * Restart even with turns running. Never a default; a caller sets it only after saying
+     * out loud what would be lost.
+     */
+    force: boolean;
   };

package/src/generated/ApiOk.ts

@@ -35,6 +35,8 @@ import type { SwarmAgent } from "./SwarmAgent";
 import type { SwarmNode } from "./SwarmNode";
 import type { SwarmStranger } from "./SwarmStranger";
 import type { ToolDef } from "./ToolDef";
+import type { UpdateOutcome } from "./UpdateOutcome";
+import type { UpdateStatus } from "./UpdateStatus";
 import type { UsageHistory } from "./UsageHistory";
 import type { ViewInfo } from "./ViewInfo";
 import type { Viewport } from "./Viewport";
@@ -107,4 +109,6 @@ export type ApiOk =
   | { "ok": "swarm_strangers"; strangers: Array<SwarmStranger> }
   | { "ok": "quotas"; quotas: Array<QuotaSnapshot> }
   | { "ok": "quota_history"; samples: Array<QuotaSample> }
-  | { "ok": "usage_history"; history: UsageHistory };
+  | { "ok": "usage_history"; history: UsageHistory }
+  | { "ok": "update"; update: UpdateStatus }
+  | { "ok": "update_applied"; outcome: UpdateOutcome };

package/src/generated/ClientMessage.ts

@@ -1,6 +1,8 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ApiCall } from "./ApiCall";
 import type { BuildId } from "./BuildId";
 import type { KeyPress } from "./KeyPress";
+import type { SessionId } from "./SessionId";
 import type { WindowId } from "./WindowId";
 
 /**
@@ -32,15 +34,38 @@ export type ClientMessage =
      * from the workspace anyway, and refusing it would be a worse answer than saying nothing.
      */
     build: BuildId;
+    /**
+     * Open in this conversation. See [`InputEvent::Attached::session`].
+     */
+    session?: SessionId | null;
   }
   | { "kind": "input" }
     & (
       | { "type": "ready"; width: number; height: number }
-      | { "type": "attached"; width: number; height: number }
+      | {
+        "type": "attached";
+        width: number;
+        height: number;
+        /**
+         * Which conversation this terminal would like to open in.
+         *
+         * `None` — every attach until `neosh "a prompt"` existed — is the ordinary placement: the
+         * most recent conversation nobody else is reading, or the screen a workspace nobody was
+         * watching kept for whoever came back. That second case is why this cannot be left to
+         * "the newest conversation wins": a terminal starting one and then attaching would be
+         * handed the abandoned screen instead, and the conversation it had just started would be
+         * running somewhere nothing on that screen mentions.
+         *
+         * A request rather than an instruction: a conversation deleted between the ask and the
+         * arrival gets the ordinary placement rather than an error nobody can act on.
+         */
+        session?: SessionId | null;
+      }
       | { "type": "detached" }
       | { "type": "key"; key: KeyPress }
       | { "type": "paste"; text: string }
       | { "type": "resize"; width: number; height: number }
+      | { "type": "scroll"; rows: number }
       | {
         "type": "viewport_changed";
         win: WindowId;
@@ -64,4 +89,14 @@ export type ClientMessage =
     )
   | { "kind": "detach" }
   | { "kind": "stop" }
-  | { "kind": "status" };
+  | { "kind": "status" }
+  | {
+    "kind": "call";
+    /**
+     * Echoed on [`ServerMessage::Called`]. Any string the caller likes — several may be in
+     * flight at once, which is the point of it being here rather than implied by order.
+     */
+    id: string;
+    call: ApiCall;
+  }
+  | { "kind": "subscribe" };

package/src/generated/InputEvent.ts

@@ -1,14 +1,34 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 import type { KeyPress } from "./KeyPress";
+import type { SessionId } from "./SessionId";
 import type { WindowId } from "./WindowId";
 
 export type InputEvent =
   | { "type": "ready"; width: number; height: number }
-  | { "type": "attached"; width: number; height: number }
+  | {
+    "type": "attached";
+    width: number;
+    height: number;
+    /**
+     * Which conversation this terminal would like to open in.
+     *
+     * `None` — every attach until `neosh "a prompt"` existed — is the ordinary placement: the
+     * most recent conversation nobody else is reading, or the screen a workspace nobody was
+     * watching kept for whoever came back. That second case is why this cannot be left to
+     * "the newest conversation wins": a terminal starting one and then attaching would be
+     * handed the abandoned screen instead, and the conversation it had just started would be
+     * running somewhere nothing on that screen mentions.
+     *
+     * A request rather than an instruction: a conversation deleted between the ask and the
+     * arrival gets the ordinary placement rather than an error nobody can act on.
+     */
+    session?: SessionId | null;
+  }
   | { "type": "detached" }
   | { "type": "key"; key: KeyPress }
   | { "type": "paste"; text: string }
   | { "type": "resize"; width: number; height: number }
+  | { "type": "scroll"; rows: number }
   | {
     "type": "viewport_changed";
     win: WindowId;

package/src/generated/InstallMethod.ts

@@ -0,0 +1,15 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * How this neosh got onto the machine, which is what decides how it may be replaced.
+ *
+ * Detected from the path of the running executable and never configured: a setting would be a
+ * thing to get wrong, and getting it wrong means writing over a file some other program believes
+ * it owns.
+ */
+export type InstallMethod =
+  | "homebrew"
+  | "npm"
+  | "cargo"
+  | "standalone"
+  | "development";

package/src/generated/LinkState.ts

@@ -3,14 +3,15 @@
 /**
  * How the connection to a peer stands, beyond the fact of it being up or not.
  *
- * `up` is the summary and this is the story, because "not connected" is three different rows on a
+ * `up` is the summary and this is the story, because "not connected" is four different rows on a
  * board: a machine being dialled that has never answered, one that was here and is being dialled
- * again, and one nothing is dialling at all — it reached us last time, or it was told to stop.
- * `attempt` counts dials since the last success, so a panel can say `try 4` instead of drawing a
- * spinner that has been spinning since Tuesday.
+ * again, one nothing is dialling at all — it reached us last time, or it was told to stop — and
+ * one that answered and is waiting on a person. `attempt` counts dials since the last success, so
+ * a panel can say `try 4` instead of drawing a spinner that has been spinning since Tuesday.
  */
 export type LinkState =
   | { "state": "connecting"; attempt: number }
   | { "state": "up" }
+  | { "state": "waiting" }
   | { "state": "retrying"; attempt: number }
   | { "state": "down" };

package/src/generated/RestartRefusal.ts

@@ -0,0 +1,12 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * What a refused [`ApiCall::UpdateRestart`] was refused for.
+ */
+export type RestartRefusal = {
+  /**
+   * The conversations with a turn in flight, workspace-wide — not just the ones this view can
+   * see, because a restart ends every one of them.
+   */
+  running: Array<string>;
+};

package/src/generated/ServerMessage.ts

@@ -1,6 +1,8 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ApiResponse } from "./ApiResponse";
 import type { BuildId } from "./BuildId";
 import type { DetachReason } from "./DetachReason";
+import type { PluginEvent } from "./PluginEvent";
 import type { UiEvent } from "./UiEvent";
 import type { WorkspaceStatus } from "./WorkspaceStatus";
 
@@ -12,4 +14,6 @@ export type ServerMessage =
   | { "kind": "refused"; reason: string; protocol_version: number }
   | { "kind": "events"; batch: Array<UiEvent> }
   | { "kind": "detached"; reason: DetachReason }
-  | { "kind": "status"; status: WorkspaceStatus };
+  | { "kind": "status"; status: WorkspaceStatus }
+  | { "kind": "called"; id: string; response: ApiResponse }
+  | { "kind": "event"; event: PluginEvent };

package/src/generated/UpdateOutcome.ts

@@ -0,0 +1,20 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { InstallMethod } from "./InstallMethod";
+
+/**
+ * What [`ApiCall::UpdateApply`] did.
+ */
+export type UpdateOutcome = { "outcome": "up_to_date"; version: string } | {
+  "outcome": "applied";
+  version: string;
+  /**
+   * Always true today, and a field rather than an assumption: a workspace holds running
+   * turns, so what happens next is a question for whoever pressed the key.
+   */
+  restart_required: boolean;
+} | {
+  "outcome": "delegated";
+  version: string;
+  command: string;
+  method: InstallMethod;
+} | { "outcome": "failed"; reason: string };

package/src/generated/UpdateStatus.ts

@@ -0,0 +1,39 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { InstallMethod } from "./InstallMethod";
+
+/**
+ * What an update would be, if there is one.
+ */
+export type UpdateStatus = {
+  /**
+   * The version running now.
+   */
+  current: string;
+  /**
+   * The newest published version, or `None` when the check has not run or could not reach the
+   * network. Absent is *unknown* rather than up to date — a failed check that reads as "you are
+   * current" is a machine that never updates and never says why.
+   */
+  latest?: string | null;
+  /**
+   * Whether `latest` is newer than `current`.
+   */
+  behind: boolean;
+  method: InstallMethod;
+  /**
+   * Whether [`ApiCall::UpdateApply`] would replace the binary, rather than name a command.
+   */
+  self_updatable: boolean;
+  /**
+   * The command to run by hand, when neosh will not do it itself.
+   */
+  upgrade_command?: string | null;
+  /**
+   * Why the last check failed, when it did. Kept so the UI can say *unknown, and here is why*.
+   */
+  error?: string | null;
+  /**
+   * Whether an update has been downloaded and is waiting for a restart.
+   */
+  restart_pending: boolean;
+};

package/src/index.ts

@@ -82,6 +82,9 @@ import type { QuotaCredits } from "./generated/QuotaCredits";
 import type { QuotaSample } from "./generated/QuotaSample";
 import type { QuotaSeverity } from "./generated/QuotaSeverity";
 import type { QuotaSnapshot } from "./generated/QuotaSnapshot";
+import type { InstallMethod } from "./generated/InstallMethod";
+import type { UpdateOutcome } from "./generated/UpdateOutcome";
+import type { UpdateStatus } from "./generated/UpdateStatus";
 import type { QuotaSource } from "./generated/QuotaSource";
 import type { QuotaWindow } from "./generated/QuotaWindow";
 import type { UsageBucket } from "./generated/UsageBucket";
@@ -143,6 +146,7 @@ export type {
   Message, PermissionDecision, PermissionMode, PermissionOption, PermissionOptionKind, PluginEvent, PluginInfo, PluginManifest, PointInfo, Pricing, ProviderEvent, ProviderOptionDescriptor,
   QuestionAnswer, QuestionOption, UserQuestion,
   CostBasis, QuotaCredits, QuotaSample, QuotaSeverity, QuotaSnapshot, QuotaSource, QuotaWindow,
+  InstallMethod, UpdateOutcome, UpdateStatus,
   UsageBucket, UsageHistory, UsageResolution, UsageScanSource,
   Rect, RepoInfo, RepoStatus, SelectShape, SessionId, SessionInfo, StatusAlign, StatusSegment, StopReason,
   SurfaceCell, SurfaceId, TextEdit, ToolCall, ToolDef, ToolResult, TurnRequest, Usage,
@@ -406,6 +410,8 @@ export interface Neosh {
   readonly event: EventApi;
   readonly swarm: SwarmApi;
   readonly quota: QuotaApi;
+  /** Whether there is a newer neosh, and becoming it. */
+  readonly update: UpdateApi;
   readonly rtp: RuntimePathApi;
   readonly path: PathApi;
   readonly timer: TimerApi;
@@ -1482,6 +1488,45 @@ export interface EventApi {
  * Everything here is data. Nothing in this API draws, which is what makes the bundled strip
  * replaceable by a panel of your own that reads exactly the same calls.
  */
+/**
+ * Finding out there is a newer neosh, and becoming it.
+ *
+ * The half that decides everything is not *is there something newer* but *may I replace this file*.
+ * A binary under a Homebrew prefix belongs to Homebrew, and writing over it leaves `brew` describing
+ * a version that is not on disk. So {@link UpdateStatus.method} is read off the running executable's
+ * path, and only a `standalone` install is ever overwritten — everything else is handed the command
+ * that would do it, for a person to run.
+ */
+export interface UpdateApi {
+  /**
+   * What is running, what is published, and what updating would mean on this machine.
+   *
+   * Answers from the last check unless `force`, so a panel row asking on every redraw costs
+   * nothing. `latest` absent is *unknown* rather than up to date — a failed check that reads as
+   * "you are current" is a machine that never updates and never says why, so draw
+   * {@link UpdateStatus.error} when it is there.
+   */
+  check(force?: boolean): Promise<UpdateStatus>;
+  /**
+   * Update, by whichever route this install takes.
+   *
+   * Never runs somebody's package manager for them: a managed install comes back as
+   * `delegated` with the command on it. A `standalone` one is downloaded, checked against the
+   * published sha256 and swapped in with a rename — which is atomic and is allowed while the old
+   * binary is still executing, and is why the answer carries `restart_required` rather than the
+   * new version simply being live.
+   */
+  apply(): Promise<UpdateOutcome>;
+  /**
+   * Restart the workspace so a downloaded update takes effect.
+   *
+   * Rejects with `Busy`, naming them, while any turn is in flight in *any* conversation — a
+   * restart ends turns belonging to terminals the caller cannot see. `force` goes ahead anyway,
+   * and is for a caller that has said out loud what would be lost.
+   */
+  restart(force?: boolean): Promise<void>;
+}
+
 export interface QuotaApi {
   /**
    * The latest snapshot for every instance that has one, freshest observation first.
@@ -1596,6 +1641,17 @@ export interface SwarmApi {
   pair(node: NodeId, opts?: { name?: string; addr?: string }): Promise<void>;
   /** Withdraw authorisation and stop connecting. Refuses for a machine your config declared. */
   unpair(node: NodeId): Promise<void>;
+  /**
+   * Call a machine something else — an SSH `Host` alias, and for the same reasons.
+   *
+   * A hostname is chosen by whoever set the machine up, is often `Mac` or `ubuntu` on every box
+   * somebody owns, and is not what its owner calls it. This wins over the announced name
+   * everywhere a `SwarmNode` is read, so every panel agrees; `null` gives the announced name back.
+   *
+   * Refuses for a machine your `config.toml` declared, naming the `name` field to change instead —
+   * an alias stored beside a config peer would be reverted by the next reload.
+   */
+  rename(node: NodeId, name: string | null): Promise<void>;
   /**
    * Dial a down peer again now, rather than waiting out its retry delay.
    *
@@ -2008,6 +2064,9 @@ function build(
       async unpair(node) {
         await c({ call: "swarm_unpair", node });
       },
+      async rename(node, name) {
+        await c({ call: "swarm_rename", node, name });
+      },
       async reconnect(node) {
         await c({ call: "swarm_reconnect", node });
       },
@@ -2036,6 +2095,17 @@ function build(
         return listener(r.swarmStreamListeners, cb);
       },
     },
+    update: {
+      async check(force) {
+        return expect(await c({ call: "update_check", force: force ?? false }), "update").update;
+      },
+      async apply() {
+        return expect(await c({ call: "update_apply" }), "update_applied").outcome;
+      },
+      async restart(force) {
+        await c({ call: "update_restart", force: force ?? false });
+      },
+    },
     quota: {
       async list() {
         return expect(await c({ call: "quota_list" }), "quotas").quotas;