@neosh/api 0.1.0 → 0.2.0

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@neosh/api",
-  "version": "0.1.0",
+  "version": "0.2.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

@@ -517,4 +517,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

@@ -41,6 +41,7 @@ export type ClientMessage =
       | { "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/InputEvent.ts

@@ -9,6 +9,7 @@ export type InputEvent =
   | { "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/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/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.
@@ -2036,6 +2081,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;