octto 0.1.3 → 0.2.0

package/README.md

@@ -104,12 +104,32 @@ Optional `~/.config/opencode/octto.json`:
 
 ```json
 {
+  "port": 3000,
   "agents": {
     "probe": { "model": "anthropic/claude-sonnet-4" }
   }
 }
 ```
 
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | number | `0` (random) | Fixed port for the browser UI server |
+| `agents` | object | - | Override agent models/settings |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OCTTO_PORT` | Override port (takes precedence over config file) |
+
+For Docker workflows, set a fixed port:
+
+```bash
+OCTTO_PORT=3000 opencode
+```
+
 ## Development
 
 ```bash

package/dist/config/index.d.ts

@@ -1,3 +1,3 @@
-export { loadCustomConfig } from "./loader";
-export type { AgentOverride, OcttoConfig } from "./schema";
-export { AgentOverrideSchema, OcttoConfigSchema } from "./schema";
+export type { AgentOverride, CustomConfig, OcttoConfig } from "./loader";
+export { loadCustomConfig, resolvePort } from "./loader";
+export { AgentOverrideSchema, OcttoConfigSchema, PortSchema } from "./schema";

package/dist/config/loader.d.ts

@@ -1,8 +1,17 @@
 import type { AgentConfig } from "@opencode-ai/sdk";
-import type { AGENTS } from "@/agents";
+import { AGENTS } from "@/agents";
 export type { AgentOverride, OcttoConfig } from "./schema";
+/**
+ * Resolve port from environment variable or config.
+ * Priority: OCTTO_PORT env var > config port > default (0 = random)
+ */
+export declare function resolvePort(configPort?: number): number;
+export interface CustomConfig {
+    agents: Record<AGENTS, AgentConfig>;
+    port: number;
+}
 /**
  * Load user configuration and merge with plugin agents.
- * Returns merged agent configs with user overrides applied.
+ * Returns merged agent configs with user overrides applied, and resolved port.
  */
-export declare function loadCustomConfig(agents: Record<AGENTS, AgentConfig>, configDir?: string): Promise<Record<AGENTS, AgentConfig>>;
+export declare function loadCustomConfig(agents: Record<AGENTS, AgentConfig>, configDir?: string): Promise<CustomConfig>;

package/dist/config/schema.d.ts

@@ -38,6 +38,7 @@ export declare const AgentOverrideSchema: Omit<v.ObjectSchema<{
         readonly issue: v.ObjectIssue | v.StringIssue | v.NumberIssue | v.MinValueIssue<number, 0> | v.MaxValueIssue<number, 2> | v.IntegerIssue<number> | v.MinValueIssue<number, 1>;
     } | undefined;
 };
+export declare const PortSchema: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 65535, undefined>]>;
 export declare const OcttoConfigSchema: v.ObjectSchema<{
     readonly agents: v.OptionalSchema<v.RecordSchema<v.EnumSchema<typeof AGENTS, undefined>, Omit<v.ObjectSchema<{
         readonly model: v.StringSchema<undefined>;
@@ -77,6 +78,7 @@ export declare const OcttoConfigSchema: v.ObjectSchema<{
             readonly issue: v.ObjectIssue | v.StringIssue | v.NumberIssue | v.MinValueIssue<number, 0> | v.MaxValueIssue<number, 2> | v.IntegerIssue<number> | v.MinValueIssue<number, 1>;
         } | undefined;
     }, undefined>, undefined>;
+    readonly port: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 65535, undefined>]>, undefined>;
 }, undefined>;
 export type AgentOverride = v.InferOutput<typeof AgentOverrideSchema>;
 export type OcttoConfig = v.InferOutput<typeof OcttoConfigSchema>;

package/dist/index.js

@@ -795,36 +795,93 @@ var AgentOverrideSchema = partial(object({
   temperature: pipe(number(), minValue(0), maxValue(2)),
   maxSteps: pipe(number(), integer(), minValue(1))
 }));
+var PortSchema = pipe(number(), integer(), minValue(0), maxValue(65535));
 var OcttoConfigSchema = object({
-  agents: optional(record(enum_(AGENTS), AgentOverrideSchema))
+  agents: optional(record(enum_(AGENTS), AgentOverrideSchema)),
+  port: optional(PortSchema)
 });
 
 // src/config/loader.ts
+var OCTTO_PORT_ENV = "OCTTO_PORT";
+var DEFAULT_PORT = 0;
+function resolvePort(configPort) {
+  const envValue = process.env[OCTTO_PORT_ENV];
+  if (envValue !== undefined) {
+    const parsed = Number(envValue);
+    if (Number.isInteger(parsed) && parsed >= 0 && parsed <= 65535) {
+      return parsed;
+    }
+  }
+  return configPort ?? DEFAULT_PORT;
+}
+var VALID_AGENT_NAMES = Object.values(AGENTS);
+function formatValidationErrors(issues) {
+  return issues.map((issue) => {
+    const path = issue.path?.map((p) => p.key).join(".") ?? "root";
+    return `  - ${path}: ${issue.message}`;
+  }).join(`
+`);
+}
 async function load(configDir) {
   const baseDir = configDir ?? join(homedir(), ".config", "opencode");
   const configPath = join(baseDir, "octto.json");
+  let parsed;
   try {
     const content = await readFile(configPath, "utf-8");
-    const parsed = JSON.parse(content);
-    const result = safeParse(OcttoConfigSchema, parsed);
-    if (!result.success) {
-      return null;
-    }
-    return result.output;
+    parsed = JSON.parse(content);
   } catch {
     return null;
   }
+  const result = safeParse(OcttoConfigSchema, parsed);
+  if (result.success) {
+    return result.output;
+  }
+  console.warn(`[octto] Config validation errors in ${configPath}:`);
+  console.warn(formatValidationErrors(result.issues));
+  if (typeof parsed !== "object" || parsed === null || !("agents" in parsed)) {
+    console.warn("[octto] No valid agents found in config, using defaults");
+    return null;
+  }
+  const rawAgents = parsed.agents;
+  if (typeof rawAgents !== "object" || rawAgents === null) {
+    console.warn("[octto] Invalid agents format, using defaults");
+    return null;
+  }
+  const validAgents = {};
+  let hasValidAgent = false;
+  for (const [name, override] of Object.entries(rawAgents)) {
+    if (!VALID_AGENT_NAMES.includes(name)) {
+      console.warn(`[octto] Unknown agent "${name}" - valid names: ${VALID_AGENT_NAMES.join(", ")}`);
+      continue;
+    }
+    const agentResult = safeParse(AgentOverrideSchema, override);
+    if (agentResult.success) {
+      validAgents[name] = agentResult.output;
+      hasValidAgent = true;
+    } else {
+      console.warn(`[octto] Invalid config for agent "${name}":`);
+      console.warn(formatValidationErrors(agentResult.issues));
+    }
+  }
+  if (!hasValidAgent) {
+    console.warn("[octto] No valid agent overrides found, using defaults");
+    return null;
+  }
+  console.warn("[octto] Partial config loaded - some overrides applied despite errors");
+  return { agents: validAgents };
 }
 async function loadCustomConfig(agents2, configDir) {
   const config = await load(configDir);
-  if (!config?.agents) {
-    return agents2;
-  }
-  const result = { ...agents2 };
-  for (const [name, override] of Object.entries(config.agents)) {
-    result[name] = { ...agents2[name], ...override };
+  const mergedAgents = { ...agents2 };
+  if (config?.agents) {
+    for (const [name, override] of Object.entries(config.agents)) {
+      mergedAgents[name] = { ...agents2[name], ...override };
+    }
   }
-  return result;
+  return {
+    agents: mergedAgents,
+    port: resolvePort(config?.port)
+  };
 }
 // src/constants.ts
 var DEFAULT_ANSWER_TIMEOUT_MS = 300000;
@@ -2463,10 +2520,10 @@ function getHtmlBundle() {
 </html>`;
 }
 // src/session/server.ts
-async function createServer(sessionId, store) {
+async function createServer(sessionId, store, configuredPort) {
   const htmlBundle = getHtmlBundle();
   const server = Bun.serve({
-    port: 0,
+    port: configuredPort ?? 0,
     fetch(req, server2) {
       const url = new URL(req.url);
       if (url.pathname === "/ws") {
@@ -2624,7 +2681,7 @@ function createSessionStore(options = {}) {
   const store = {
     async startSession(input) {
       const sessionId = generateSessionId();
-      const { server, port } = await createServer(sessionId, store);
+      const { server, port } = await createServer(sessionId, store, options.port);
       const url = `http://localhost:${port}`;
       const session = {
         id: sessionId,
@@ -16484,7 +16541,7 @@ function createOcttoTools(sessions, client) {
 // src/index.ts
 var Octto = async ({ client }) => {
   const customConfig = await loadCustomConfig(agents);
-  const sessions = createSessionStore();
+  const sessions = createSessionStore({ port: customConfig.port });
   const tracked = new Map;
   const tools = createOcttoTools(sessions, client);
   const originalExecute = tools.start_session.execute;
@@ -16502,7 +16559,7 @@ var Octto = async ({ client }) => {
   return {
     tool: tools,
     config: async (config2) => {
-      config2.agent = { ...config2.agent, ...customConfig };
+      config2.agent = { ...config2.agent, ...customConfig.agents };
     },
     event: async ({ event }) => {
       if (event.type !== "session.deleted")

package/dist/session/server.d.ts

@@ -3,7 +3,7 @@ import type { SessionStore } from "./sessions";
 interface WsData {
     sessionId: string;
 }
-export declare function createServer(sessionId: string, store: SessionStore): Promise<{
+export declare function createServer(sessionId: string, store: SessionStore, configuredPort?: number): Promise<{
     server: Server<WsData>;
     port: number;
 }>;

package/dist/session/sessions.d.ts

@@ -3,6 +3,8 @@ import { type BaseConfig, type EndSessionOutput, type GetAnswerInput, type GetAn
 export interface SessionStoreOptions {
     /** Skip opening browser - useful for tests */
     skipBrowser?: boolean;
+    /** Fixed port for the server (0 = random available port) */
+    port?: number;
 }
 export interface SessionStore {
     startSession: (input: StartSessionInput) => Promise<StartSessionOutput>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octto",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "OpenCode plugin that turns rough ideas into designs through branch-based exploration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",