octto 0.1.4 → 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 { 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,11 +795,25 @@ 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) => {
@@ -858,14 +872,16 @@ async function load(configDir) {
 }
 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;
@@ -2504,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") {
@@ -2665,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,
@@ -16525,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;
@@ -16543,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.4",
+  "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",