@moxxy/sdk 0.37.2 → 0.39.0

package/src/provider-login-bridge.ts

@@ -17,12 +17,40 @@
  * depend on, so the two ends can never drift.
  */
 
+import { z } from 'zod';
+
 /** The byte that brackets a prompt marker. Absent from normal CLI output. */
 const NUL = '\u0000';
 
 /** Tag distinguishing a login-prompt marker from any other NUL-bracketed run. */
 const PROMPT_TAG = 'moxxy.login.prompt';
 
+/** Tag distinguishing a browser-authorization URL from normal login output. */
+const AUTH_URL_TAG = 'moxxy.login.auth_url';
+
+const LoginAuthUrlSchema = z
+  .string()
+  .max(8192)
+  .refine((value) => {
+    try {
+      const url = new URL(value);
+      return (
+        (url.protocol === 'http:' || url.protocol === 'https:') &&
+        url.username === '' &&
+        url.password === ''
+      );
+    } catch {
+      return false;
+    }
+  }, 'must be an http(s) URL without embedded credentials');
+
+const LoginAuthUrlMarkerSchema = z
+  .object({
+    tag: z.literal(AUTH_URL_TAG),
+    url: LoginAuthUrlSchema,
+  })
+  .strict();
+
 export interface LoginPromptRequest {
   /** The question to show the user, verbatim from `ctx.prompt`. */
   readonly question: string;
@@ -33,7 +61,8 @@ export interface LoginPromptRequest {
 /** One decoded item from a login subprocess's stdout stream. */
 export type LoginStreamItem =
   | { readonly type: 'output'; readonly text: string }
-  | { readonly type: 'prompt'; readonly prompt: LoginPromptRequest };
+  | { readonly type: 'prompt'; readonly prompt: LoginPromptRequest }
+  | { readonly type: 'auth_url'; readonly url: string };
 
 /**
  * Serialize a prompt request as a NUL-bracketed marker for stdout. The
@@ -59,6 +88,28 @@ export function decodeLoginPrompt(segment: string): LoginPromptRequest | null {
   }
 }
 
+/**
+ * Serialize the browser authorization URL for a GUI host. Validation happens
+ * before a marker reaches stdout: a provider-controlled URL may only be a
+ * credential-free HTTP(S) URL, never a shell-adjacent custom/file scheme.
+ */
+export function encodeLoginAuthUrl(url: string): string {
+  const marker = LoginAuthUrlMarkerSchema.parse({ tag: AUTH_URL_TAG, url });
+  return NUL + JSON.stringify(marker) + NUL;
+}
+
+/** Decode and validate one inter-NUL authorization-URL marker. */
+export function decodeLoginAuthUrl(segment: string): string | null {
+  if (!segment.startsWith('{')) return null;
+  try {
+    const parsed: unknown = JSON.parse(segment);
+    const marker = LoginAuthUrlMarkerSchema.safeParse(parsed);
+    return marker.success ? marker.data.url : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Streaming scanner for a login subprocess's stdout. Feed it chunks; it
  * returns the ordered output / prompt items decoded so far, holding back any
@@ -84,9 +135,16 @@ export function createLoginStreamScanner(): {
         if (open > 0) out.push({ type: 'output', text: buf.slice(0, open) });
         const segment = buf.slice(open + 1, close);
         const prompt = decodeLoginPrompt(segment);
+        const authUrl = prompt ? null : decodeLoginAuthUrl(segment);
         // A NUL-bracketed run that isn't a valid marker is anomalous; surface
         // its inner text as output rather than swallowing it.
-        out.push(prompt ? { type: 'prompt', prompt } : { type: 'output', text: segment });
+        out.push(
+          prompt
+            ? { type: 'prompt', prompt }
+            : authUrl !== null
+              ? { type: 'auth_url', url: authUrl }
+              : { type: 'output', text: segment },
+        );
         buf = buf.slice(close + 1);
       }
       // Flush any plain text that precedes a still-incomplete marker (or all

package/src/provider-utils.test.ts

@@ -152,3 +152,57 @@ describe('resolveProviderTools', () => {
     expect(resolveProviderTools([webSearch], models, 'catalog-drift').tools).toEqual([webSearch]);
   });
 });
+
+/**
+ * Field descriptions are the only place a tool author can say what a parameter
+ * means, and the model is the audience. They were dropped on the floor: every
+ * `.describe()` in every moxxy tool reached the provider as nothing at all,
+ * which is how a model ends up inventing `tab_id: "current"` for a field whose
+ * description reads "Omit for the active tab".
+ */
+describe('zodToJsonSchema — descriptions', () => {
+  it('carries a field description through to the model', () => {
+    const out = zodToJsonSchema(z.object({ a: z.string().describe('Co to jest a') })) as {
+      properties: Record<string, Record<string, unknown>>;
+    };
+
+    expect(out.properties.a).toEqual({ type: 'string', description: 'Co to jest a' });
+  });
+
+  it('keeps a description that sits under a wrapper', () => {
+    expect(zodToJsonSchema(z.string().describe('opis').optional())).toEqual({
+      type: 'string',
+      description: 'opis',
+    });
+  });
+
+  it('lets the outermost description win when a wrapper carries one too', () => {
+    const schema = z.string().describe('wewnetrzny').optional().describe('zewnetrzny');
+
+    expect(zodToJsonSchema(schema)).toEqual({ type: 'string', description: 'zewnetrzny' });
+  });
+
+  it('describes a whole object, an enum and an array element too', () => {
+    const out = zodToJsonSchema(
+      z
+        .object({
+          mode: z.enum(['a', 'b']).describe('Tryb'),
+          tags: z.array(z.string()).describe('Etykiety'),
+        })
+        .describe('Cale wejscie'),
+    ) as { description: string; properties: Record<string, Record<string, unknown>> };
+
+    expect(out.description).toBe('Cale wejscie');
+    expect(out.properties.mode?.description).toBe('Tryb');
+    expect(out.properties.tags?.description).toBe('Etykiety');
+  });
+
+  it('adds no description key when the author wrote none', () => {
+    expect(zodToJsonSchema(z.string())).toEqual({ type: 'string' });
+    expect(zodToJsonSchema(z.object({ a: z.string() }))).toEqual({
+      type: 'object',
+      properties: { a: { type: 'string' } },
+      required: ['a'],
+    });
+  });
+});

package/src/provider-utils.ts

@@ -80,7 +80,29 @@ export function toFriendlyError(
  */
 const MAX_SCHEMA_DEPTH = 32;
 
+/**
+ * Convert, then re-attach the author's `.describe()` text.
+ *
+ * A field description is the only place a tool author gets to say what a
+ * parameter means, and the model is the audience — dropping it leaves the
+ * model guessing at values (`tab_id: "current"` for a field documented as
+ * "omit for the active tab"). `description` is standard JSON Schema, so every
+ * provider either uses it or ignores it.
+ *
+ * Doing it here rather than at each of the dozen returns below also fixes the
+ * wrappers for free: `.describe()` may sit on the ZodOptional/ZodEffects OR on
+ * the type inside it, and each level of the recursion re-enters through this
+ * function. The outermost wins, because it applies last.
+ */
 export function zodToJsonSchema(schema: unknown, depth = 0): unknown {
+  const json = convertSchema(schema, depth);
+  const description = (schema as { _def?: { description?: string } } | null)?._def?.description;
+  if (typeof description !== 'string' || !description) return json;
+  if (typeof json !== 'object' || json === null || Array.isArray(json)) return json;
+  return { ...json, description };
+}
+
+function convertSchema(schema: unknown, depth: number): unknown {
   if (depth > MAX_SCHEMA_DEPTH) return {};
   const s = schema as { _def?: { typeName?: string }; toJSON?: () => unknown };
   // Only honor a pre-serialized schema's `toJSON` for NON-zod objects (a plain

package/src/provider.ts

@@ -160,6 +160,16 @@ export interface ModelDescriptor {
 export interface LLMProvider {
   readonly name: string;
   readonly models: ReadonlyArray<ModelDescriptor>;
+  /**
+   * Optional provider-owned metadata preparation for a dynamically selected
+   * model. The runtime awaits it before it calculates context budgets, so a
+   * provider whose catalog is discovered at runtime can publish the exact
+   * descriptor without trusting a client-supplied context-window value.
+   */
+  prepareModel?(
+    model: string,
+    options?: { readonly signal?: AbortSignal },
+  ): Promise<void>;
   stream(req: ProviderRequest): AsyncIterable<ProviderEvent>;
   countTokens(req: Pick<ProviderRequest, 'model' | 'messages' | 'system' | 'tools'>): Promise<number>;
 }
@@ -202,6 +212,18 @@ export interface ProviderAuthContext {
    * whether they're running inside a wizard or a one-shot command.
    */
   readonly write: (chunk: string) => void;
+  /**
+   * True when a GUI host owns browser opening. OAuth implementations still
+   * build the loopback URL and report it through {@link onAuthUrl}, but must not
+   * invoke their process-local browser helper.
+   */
+  readonly noOpen?: boolean;
+  /**
+   * Browser authorization URL produced by a loopback flow. GUI hosts relay it
+   * over their authenticated transport, validate it again, and open it using
+   * their native browser API.
+   */
+  readonly onAuthUrl?: (url: string) => void;
   /**
    * Optional single-line input prompt. Present when the host has an
    * interactive TTY; absent in headless runs. Flows that need the user to
@@ -305,6 +327,12 @@ export interface ProviderOAuthStatus {
 export interface ProviderDef {
   readonly name: string;
   readonly models: ReadonlyArray<ModelDescriptor>;
+  /**
+   * True when the provider can return its current model catalog at runtime.
+   * Hosts use this capability signal to offer live discovery instead of
+   * presenting the provider's build-time fallback catalog as authoritative.
+   */
+  readonly supportsLiveModelDiscovery?: boolean;
   createClient(config: Record<string, unknown>): LLMProvider;
   /**
    * Optional provider-owned credential/config resolver. Hosts call this before

package/src/server.ts

@@ -73,3 +73,14 @@ export {
   MOXXY_WS_SUBPROTOCOL,
   MOXXY_WS_BEARER_PROTOCOL_PREFIX,
 } from './channel-auth.js';
+export {
+  execExecutableTargetSync,
+  executableCandidates,
+  findExecutable,
+  resolveExecutableTarget,
+  spawnExecutableTarget,
+  type ExecutableSearchOptions,
+  type ExecutableTarget,
+  type SafeExecFileSyncOptions,
+  type SafeSpawnOptions,
+} from './process-invocation.js';