overmux 0.0.3 → 0.0.5

package/src/internal/shared/protocol.ts

@@ -1,10 +1,11 @@
 import { z } from "zod";
+import { instanceIdSchema } from "@overmux/shared";
 
 import { notificationSchema } from "../../public/notifications";
 
 // Compatibility gate, not negotiation: open tabs may still run older client assets.
 // The exact version rejects incompatible runtime manifest and wire formats before later traffic.
-export const protocolVersion = 9 as const;
+export const protocolVersion = 10 as const;
 
 // Application-defined WebSocket close codes shared by server and browser transports.
 export const webSocketCloseCode = {
@@ -139,7 +140,15 @@ export const protocolErrorMessageSchema = z.object({
   type: z.literal("error"),
 });
 
+export const serverInfoMessageSchema = z
+  .object({
+    type: z.literal("server-info"),
+    instanceId: instanceIdSchema,
+  })
+  .strict();
+
 export const serverProtocolMessageSchema = z.discriminatedUnion("type", [
+  serverInfoMessageSchema,
   resourceResultMessageSchema,
   resourceInvalidatedMessageSchema,
   streamOpenedMessageSchema,

package/src/public/ai-context.ts

@@ -1,38 +1,16 @@
 import {
-  packageSourceSnippet,
-  techStackRecommendationsSnippet,
-  type AiContextSnippet,
-} from "@overmux/shared";
+  aiContextContentBySnippet,
+  type AiContextSnippetDefinition,
+} from "@overmux/ai-context";
 
 export {
+  coreAiContextSnippets,
+  defaultAiContextSnippets,
   packageSourceSnippet,
   techStackRecommendationsSnippet,
   type AiContextSnippet,
-};
-export type AiContextSnippetDefinition = readonly AiContextSnippet[];
-
-export const coreAiContextSnippets = [
-  packageSourceSnippet,
-] as const satisfies AiContextSnippetDefinition;
-export const defaultAiContextSnippets = [
-  ...coreAiContextSnippets,
-  techStackRecommendationsSnippet,
-] as const satisfies AiContextSnippetDefinition;
-
-const packageSourceSnippetContent = `Overmux ships with documentation and TypeScript source.
-
-Run \`overmux docs\` to find the installed documentation and source for the overmux cli.
-
-E.g. \`node_modules/overmux\` and \`node_modules/@overmux/xterm\`.
-
-Inspect these files so guidance matches the versions used by the application.`;
-
-const techStackRecommendationsSnippetContent = `Prefer pnpm as the package manager, TanStack Router for routing, shadcn/ui for UI components, and Zod for schemas and runtime validation. Follow the application's established stack when it already differs.`;
-
-const aiContextContentBySnippet: Record<AiContextSnippet, string> = {
-  [packageSourceSnippet]: packageSourceSnippetContent,
-  [techStackRecommendationsSnippet]: techStackRecommendationsSnippetContent,
-};
+  type AiContextSnippetDefinition,
+} from "@overmux/ai-context";
 
 export const composeAiContext = (snippets: AiContextSnippetDefinition) =>
   snippets.length === 0

package/src/public/client.ts

@@ -7,6 +7,7 @@ export {
   writeClipboardText,
 } from "../internal/client/clipboard";
 export type { OvermuxServerApi } from "../internal/client/browser-api";
+export type { InstanceIdentity } from "@overmux/shared";
 export {
   createOvermuxHooks,
   type ResourceResult,
@@ -27,15 +28,9 @@ export type {
   OvermuxThemeToken,
 } from "../internal/client/theme-scope";
 export {
-  chordPrefixSchema,
-  commandBindingSchema,
   defineCommandRegistry,
   defineOvermuxClient,
-  formatKeyBinding,
   formatShortcutBinding,
-  keyBindingSchema,
-  matchesKeyBinding,
-  shortcutBindingSchema,
 } from "../internal/client/client-definition";
 export {
   skipToken,

package/src/public/config.ts

@@ -6,39 +6,56 @@ import type { ResourceContract, StreamContract } from "./contracts";
 
 export type RuntimeDisposer = () => Promise<void> | void;
 
-export type HandlerContext = {
-  invalidate: (contract: ResourceContract, input?: unknown) => void;
-  signal: AbortSignal;
+export type InstanceContext = {
+  getInstanceId: () => string;
+  getDeepLinkPrefix: () => string;
 };
 
-export type OperationContext = HandlerContext & {
-  notifications: Notifications;
+type ResourceInputMap = Readonly<Record<string, unknown>>;
+
+// Keep IDs paired with their raw inputs when checking calls and reusable handlers.
+type InvalidationArguments<TInputs extends ResourceInputMap> = {
+  [TId in keyof TInputs & string]: [resourceId: TId, input?: TInputs[TId]];
+}[keyof TInputs & string];
+
+export type HandlerContext<TInputs extends ResourceInputMap = {}> = {
+  instance: InstanceContext;
+  invalidate: (...args: InvalidationArguments<TInputs>) => void;
+  signal: AbortSignal;
 };
 
+export type OperationContext<TInputs extends ResourceInputMap = {}> =
+  HandlerContext<TInputs> & {
+    notifications: Notifications;
+  };
+
 export type OperationDefinition<
   TInput extends z.ZodType = z.ZodType,
   TOutput extends z.ZodType = z.ZodVoid,
+  TContext = OperationContext,
 > = {
   handle: (
     input: z.output<TInput>,
-    context: OperationContext,
+    context: TContext,
   ) => Promise<z.input<NoInfer<TOutput>>> | z.input<NoInfer<TOutput>>;
   input: TInput;
   output: TOutput;
 };
 
+// Infer schemas from this definition, not a surrounding operation map's broad constraint.
 export const defineOperation = <
   TInput extends z.ZodType,
   TOutput extends z.ZodType = z.ZodVoid,
+  TContext = OperationContext,
 >({
   handle,
   input,
   output,
 }: {
-  handle: OperationDefinition<TInput, TOutput>["handle"];
+  handle: OperationDefinition<TInput, TOutput, TContext>["handle"];
   input: TInput;
   output?: TOutput;
-}): OperationDefinition<TInput, TOutput> => ({
+}): OperationDefinition<NoInfer<TInput>, NoInfer<TOutput>, TContext> => ({
   handle,
   input,
   output: (output ?? z.void()) as TOutput,
@@ -47,26 +64,28 @@ export const defineOperation = <
 export type QueryResourceDefinition<
   TInput extends z.ZodType = z.ZodType,
   TOutput extends z.ZodType = z.ZodType,
+  TContext = HandlerContext,
 > = {
   contract: ResourceContract<TInput, TOutput>;
   kind: "query";
   read: (
     input: z.output<TInput>,
-    context: HandlerContext,
+    context: TContext,
   ) => Promise<z.input<NoInfer<TOutput>>> | z.input<NoInfer<TOutput>>;
 };
 
 export type SubscriptionResourceDefinition<
   TInput extends z.ZodType = z.ZodType,
   TOutput extends z.ZodType = z.ZodType,
+  TContext = HandlerContext,
 > = {
   contract: ResourceContract<TInput, TOutput>;
   kind: "subscription";
-  read: QueryResourceDefinition<TInput, TOutput>["read"];
+  read: QueryResourceDefinition<TInput, TOutput, TContext>["read"];
   subscribe: (
     input: z.output<TInput>,
     invalidate: () => void,
-    context: HandlerContext,
+    context: TContext,
   ) => RuntimeDisposer;
 };
 
@@ -87,8 +106,16 @@ export type DerivedResourceDefinition<
 type AnyZodType = z.ZodType<any, any, any>;
 
 export type ResourceDefinition =
-  | QueryResourceDefinition<AnyZodType, AnyZodType>
-  | SubscriptionResourceDefinition<AnyZodType, AnyZodType>
+  | QueryResourceDefinition<
+      AnyZodType,
+      AnyZodType,
+      HandlerContext<ResourceInputMap>
+    >
+  | SubscriptionResourceDefinition<
+      AnyZodType,
+      AnyZodType,
+      HandlerContext<ResourceInputMap>
+    >
   | DerivedResourceDefinition<AnyZodType, AnyZodType, any, any>;
 
 export type StreamSession<TClientMessage = unknown> = {
@@ -100,11 +127,12 @@ export type StreamHandlerDefinition<
   TInput extends z.ZodType = z.ZodType,
   TClientMessage extends z.ZodType = z.ZodType,
   TServerMessage extends z.ZodType = z.ZodType,
+  TContext = HandlerContext,
 > = {
   contract: StreamContract<TInput, TClientMessage, TServerMessage>;
   open: (
     input: z.output<TInput>,
-    context: HandlerContext & {
+    context: TContext & {
       emit: (message: z.input<NoInfer<TServerMessage>>) => void;
       fail: (cause: unknown) => void;
     },
@@ -117,10 +145,21 @@ export const defineStreamHandler = <
   TInput extends z.ZodType,
   TClientMessage extends z.ZodType,
   TServerMessage extends z.ZodType,
+  TContext = HandlerContext,
 >(
   contract: StreamContract<TInput, TClientMessage, TServerMessage>,
-  open: StreamHandlerDefinition<TInput, TClientMessage, TServerMessage>["open"],
-): StreamHandlerDefinition<TInput, TClientMessage, TServerMessage> => ({
+  open: StreamHandlerDefinition<
+    TInput,
+    TClientMessage,
+    TServerMessage,
+    TContext
+  >["open"],
+): StreamHandlerDefinition<
+  TInput,
+  TClientMessage,
+  TServerMessage,
+  TContext
+> => ({
   contract,
   open,
 });
@@ -130,6 +169,10 @@ type ResourceContracts = Record<
   ResourceContract<AnyZodType, AnyZodType>
 >;
 
+type ResourceInputs<TContracts extends ResourceContracts> = {
+  [TId in keyof TContracts]: z.input<TContracts[TId]["input"]>;
+};
+
 type DependencyOutputs<
   TContracts extends ResourceContracts,
   TDependencies extends Record<string, unknown>,
@@ -148,17 +191,29 @@ type DependencySource<TDependencies> = {
     : { dependencies?: never };
 };
 
-type QueryFor<TContract extends ResourceContract<AnyZodType, AnyZodType>> = {
+type QueryFor<
+  TContract extends ResourceContract<AnyZodType, AnyZodType>,
+  TContracts extends ResourceContracts,
+> = {
   contract: TContract;
 } & Omit<
-  QueryResourceDefinition<TContract["input"], TContract["output"]>,
+  QueryResourceDefinition<
+    TContract["input"],
+    TContract["output"],
+    HandlerContext<ResourceInputs<NoInfer<TContracts>>>
+  >,
   "contract"
 >;
 
 type SubscriptionFor<
   TContract extends ResourceContract<AnyZodType, AnyZodType>,
+  TContracts extends ResourceContracts,
 > = { contract: TContract } & Omit<
-  SubscriptionResourceDefinition<TContract["input"], TContract["output"]>,
+  SubscriptionResourceDefinition<
+    TContract["input"],
+    TContract["output"],
+    HandlerContext<ResourceInputs<NoInfer<TContracts>>>
+  >,
   "contract"
 >;
 
@@ -180,8 +235,8 @@ type ConfiguredResource<
   TDependencies,
   TId extends keyof TContracts,
 > =
-  | QueryFor<TContracts[TId]>
-  | SubscriptionFor<TContracts[TId]>
+  | QueryFor<TContracts[TId], TContracts>
+  | SubscriptionFor<TContracts[TId], TContracts>
   | (TId extends keyof TDependencies
       ? TDependencies[TId] extends Record<
           string,
@@ -207,26 +262,97 @@ export type AuthDuration = `${number}${"m" | "h" | "d"}`;
 export type AuthConfigDefinition = {
   mode: "cli-login";
   origins?: string[];
-  sessionLifetime?: "never" | AuthDuration;
+  sessionLifetime?: "forever" | AuthDuration;
   trustedProxyPeer?: string;
 };
 
 export type ServerConfigDefinition = {
   host?: string;
-  logFile?: string;
   port?: number;
   productionWebAssetsDir?: string;
   watch?: boolean;
 };
 
-type StreamDefinitions = Readonly<
-  Record<string, StreamHandlerDefinition<AnyZodType, AnyZodType, AnyZodType>>
+type StreamDefinitions<TContext = HandlerContext<ResourceInputMap>> = Readonly<
+  Record<
+    string,
+    StreamHandlerDefinition<AnyZodType, AnyZodType, AnyZodType, TContext>
+  >
 >;
 
 type OperationDefinitions = Readonly<
-  Record<string, OperationDefinition<AnyZodType, AnyZodType>>
+  Record<
+    string,
+    OperationDefinition<
+      AnyZodType,
+      AnyZodType,
+      OperationContext<ResourceInputMap>
+    >
+  >
 >;
 
+type OperationInputs = Record<string, AnyZodType>;
+
+type OperationOutputSchema<
+  TOutputs,
+  TId extends PropertyKey,
+> = TId extends keyof TOutputs
+  ? TOutputs[TId] extends z.ZodType
+    ? TOutputs[TId]
+    : z.ZodVoid
+  : z.ZodVoid;
+
+type ConfiguredOperations<
+  TInputs extends OperationInputs,
+  TOutputs,
+  TContracts extends ResourceContracts,
+> = {
+  [TId in keyof TInputs]: {
+    input: TInputs[TId];
+    output?: OperationOutputSchema<TOutputs, TId>;
+    handle: OperationDefinition<
+      TInputs[TId],
+      OperationOutputSchema<TOutputs, TId>,
+      OperationContext<ResourceInputs<TContracts>>
+    >["handle"];
+  };
+} & {
+  [TId in keyof TOutputs]: TOutputs[TId] extends z.ZodType
+    ? { output: TOutputs[TId] }
+    : { output?: never };
+};
+
+type NormalizedOperations<
+  TInputs extends OperationInputs,
+  TOutputs,
+  TContracts extends ResourceContracts,
+> = {
+  [TId in keyof TInputs]: OperationDefinition<
+    TInputs[TId],
+    OperationOutputSchema<TOutputs, TId>,
+    OperationContext<ResourceInputs<TContracts>>
+  >;
+};
+
+const normalizeOperations = <
+  TInputs extends OperationInputs,
+  TOutputs,
+  TContracts extends ResourceContracts,
+>(
+  operations: ConfiguredOperations<TInputs, TOutputs, TContracts> | undefined,
+): NormalizedOperations<TInputs, TOutputs, TContracts> | undefined => {
+  if (operations === undefined) {
+    return undefined;
+  }
+  // Preserve every key and handler; only absent output schemas become ZodVoid.
+  return Object.fromEntries(
+    Object.entries(operations).map(([id, definition]) => [
+      id,
+      { ...definition, output: definition.output ?? z.void() },
+    ]),
+  ) as NormalizedOperations<TInputs, TOutputs, TContracts>;
+};
+
 export type ConfigDefinition<
   TResources extends Readonly<Record<string, unknown>> = Readonly<
     Record<string, ResourceDefinition>
@@ -245,6 +371,7 @@ export type OvermuxConfigDefinition<
   aiContextSnippets?: AiContextSnippetDefinition;
   auth: AuthConfigDefinition;
   debug?: boolean;
+  instanceId?: string | ((context: { port: number }) => string);
   server: TServer;
   vite?: string;
 };
@@ -271,16 +398,21 @@ export const defineOvermuxServer = <
   const TContracts extends ResourceContracts = {},
   const TDependencies = {},
   const TStreams extends StreamDefinitions = {},
-  const TOperations extends OperationDefinitions = {},
+  const TInputs extends OperationInputs = {},
+  const TOutputs = {},
 >(definition: {
-  operations?: TOperations;
+  operations?: ConfiguredOperations<TInputs, TOutputs, NoInfer<TContracts>>;
   resources: ConfiguredResources<TContracts, TDependencies>;
-  streams?: TStreams;
+  streams?: TStreams &
+    StreamDefinitions<HandlerContext<ResourceInputs<NoInfer<TContracts>>>>;
 }): ConfigDefinition<
   ConfiguredResources<TContracts, TDependencies>,
   TStreams,
-  TOperations
-> => definition;
+  NormalizedOperations<TInputs, TOutputs, TContracts>
+> => ({
+  ...definition,
+  operations: normalizeOperations(definition.operations),
+});
 
 export const defineOvermuxConfig = <const TServer extends ConfigDefinition>(
   definition: OvermuxConfigDefinition<TServer>,

package/src/public/index.ts

@@ -21,6 +21,7 @@ export type {
   ConfigDefinition,
   DerivedResourceDefinition,
   HandlerContext,
+  InstanceContext,
   OperationContext,
   OperationDefinition,
   OvermuxConfigDefinition,
@@ -49,6 +50,7 @@ export type {
 } from "./contracts";
 export { notificationLinkSchema, notificationSchema } from "./notifications";
 export type { Notification, Notifications } from "./notifications";
+export type { InstanceIdentity } from "@overmux/shared";
 export {
   createOvermuxSettingsPath,
   overmuxLogoutPath,

package/src/public/server.ts

@@ -1,16 +1 @@
-export {
-  checkOvermux,
-  type CheckDiagnostic,
-  type CheckOvermuxOptions,
-  type CheckResult,
-} from "../internal/server/check-overmux";
-export {
-  getOvermuxPaths,
-  type GetOvermuxPathsOptions,
-  type OvermuxPaths,
-} from "../internal/server/paths";
-export {
-  startOvermuxServer,
-  type OvermuxServer,
-  type OvermuxServerOptions,
-} from "../internal/server/start-overmux-server";
+export { getOvermuxPaths } from "../internal/server/paths";

package/dist/docs/100-introduction/100-what-is-overmux.md

@@ -1,7 +0,0 @@
----
-title: What is Overmux?
----
-
-Overmux is a web-based, customizable dev environment. Designed for coding using Agents.
-
-

package/dist/docs/300-fundamentals/100-project-structure.md

@@ -1,23 +0,0 @@
----
-title: Project Structure
----
-
-`overmux init` creates this minimal userland application:
-
-```text
-.gitignore
-mise.toml               Mise installations only
-package.json
-pnpm-lock.yaml
-overmux.config.ts       authentication, server, Vite, and production settings
-src/server/index.ts     trusted resources, streams, and operations
-src/ui/app.tsx          browser application definition
-src/ui/index.html       browser document
-src/ui/main.tsx         React and Overmux host entry point
-src/ui/styles.css       application styles
-vite.config.ts          browser development and production build configuration
-```
-
-The server and UI are separate trust boundaries. `src/server/index.ts` runs as trusted Node.js code. Files under `src/ui` run in the browser and communicate with the server through Overmux's public APIs.
-
-The generated application has no shared directory. Add browser-safe shared schemas only when both sides need them.

package/dist/docs/300-fundamentals/200-configuration.md

@@ -1,3 +0,0 @@
----
-title: Configuration
----

package/dist/docs/300-fundamentals/300-theming.md

@@ -1,3 +0,0 @@
----
-title: Theming
----

package/dist/docs/300-fundamentals/400-server.md

@@ -1,3 +0,0 @@
----
-title: Server
----

package/dist/docs/300-fundamentals/500-client.md

@@ -1,3 +0,0 @@
----
-title: Client
----

package/dist/docs/300-fundamentals/600-operations.md

@@ -1,3 +0,0 @@
----
-title: Operations
----

package/dist/docs/300-fundamentals/700-resources.md

@@ -1,3 +0,0 @@
----
-title: Resources
----

package/dist/docs/300-fundamentals/800-streams.md

@@ -1,3 +0,0 @@
----
-title: Streams
----

package/dist/docs/300-fundamentals/900-authentication-and-security.md

@@ -1,3 +0,0 @@
----
-title: Authentication and Security
----

package/dist/docs/400-reference/100-configuration.md

@@ -1,3 +0,0 @@
----
-title: Configuration
----

package/dist/docs/400-reference/200-server-api.md

@@ -1,3 +0,0 @@
----
-title: Server API
----

package/dist/docs/400-reference/300-client-api.md

@@ -1,20 +0,0 @@
----
-title: Client API
----
-
-## Clipboard
-
-```ts
-import { readClipboardText, writeClipboardText } from "overmux/client";
-
-await writeClipboardText("Text to copy");
-const text = await readClipboardText();
-```
-
-`readClipboardText(): Promise<string>` reads the system clipboard through `navigator.clipboard.readText()`. It never reads through the desktop bridge.
-
-`writeClipboardText(text: string): Promise<void>` uses Overmux's version-1 desktop write bridge when present, otherwise `navigator.clipboard.writeText()`. Desktop writes are fire-and-forget: resolution confirms dispatch, not completion or acceptance by the host. Existing host origin and active-frame checks still apply.
-
-Both reject on unavailable browser APIs, browser permission failures, or synchronous desktop dispatch failures. Browser secure-context, focus, permissions, and user-activation restrictions still apply. These APIs target the system clipboard, not the X11 primary selection. Only read clipboard data you need and trust the source of text you write.
-
-For terminal-program access via OSC 52, use the opt-in factories from `@overmux/xterm/client` rather than wiring platform bridges in application code.

package/dist/docs/400-reference/400-cli/400-check.md

@@ -1,20 +0,0 @@
----
-title: "overmux check"
-description: "Validate an Overmux configuration"
----
-
-# `overmux check`
-
-Validate an Overmux configuration.
-
-## Usage
-
-```text
-overmux check [--config path]
-```
-
-## Options
-
-| Flag | Description | Default |
-| --- | --- | --- |
-| `--config <path>, -c <path>` | Configuration file | `$XDG_CONFIG_HOME/overmux/overmux.config.ts` |