octto 0.1.4 → 0.3.0

package/README.md

@@ -104,12 +104,60 @@ 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 |
+| `fragments` | object | - | Custom instructions injected into agent prompts |
+
+### Fragments
+
+Inject custom instructions into agent prompts. Useful for customizing agent behavior per-project or globally.
+
+**Global config** (`~/.config/opencode/octto.json`):
+
+```json
+{
+  "fragments": {
+    "octto": ["Always suggest 3 implementation approaches"],
+    "probe": ["Include emoji in every question"],
+    "bootstrapper": ["Focus on technical feasibility"]
+  }
+}
+```
+
+**Project config** (`.octto/fragments.json` in your project root):
+
+```json
+{
+  "octto": ["This project uses React - focus on component patterns"],
+  "probe": ["Ask about testing strategy for each feature"]
+}
+```
+
+Fragments are merged: global fragments load first, project fragments append. Each fragment becomes a bullet point in a `<user-instructions>` block prepended to the agent's system prompt.
+
+### 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, Fragments, OcttoConfig } from "./loader";
+export { loadCustomConfig, resolvePort } from "./loader";
+export { AgentOverrideSchema, FragmentsSchema, OcttoConfigSchema, PortSchema } from "./schema";

package/dist/config/loader.d.ts

@@ -1,8 +1,19 @@
 import type { AgentConfig } from "@opencode-ai/sdk";
 import { AGENTS } from "@/agents";
-export type { AgentOverride, OcttoConfig } from "./schema";
+import { type Fragments } from "./schema";
+export type { AgentOverride, Fragments, 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;
+    fragments: Fragments;
+}
 /**
  * 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,8 @@ 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 FragmentsSchema: v.OptionalSchema<v.RecordSchema<v.EnumSchema<typeof AGENTS, undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, 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 +79,9 @@ 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>;
+    readonly fragments: v.OptionalSchema<v.RecordSchema<v.EnumSchema<typeof AGENTS, undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
 }, undefined>;
 export type AgentOverride = v.InferOutput<typeof AgentOverrideSchema>;
+export type Fragments = v.InferOutput<typeof FragmentsSchema>;
 export type OcttoConfig = v.InferOutput<typeof OcttoConfigSchema>;

package/dist/hooks/fragment-injector.d.ts

@@ -0,0 +1,37 @@
+type FragmentsRecord = Record<string, string[]> | undefined;
+/**
+ * Format fragments array as an XML block to prepend to agent prompts.
+ */
+export declare function formatFragmentsBlock(fragments: string[] | undefined): string;
+/**
+ * Merge global and project fragments.
+ * Global fragments come first, project fragments append.
+ */
+export declare function mergeFragments(global: FragmentsRecord, project: FragmentsRecord): Record<string, string[]>;
+/**
+ * Load project-level fragments from .octto/fragments.json
+ */
+export declare function loadProjectFragments(projectDir: string): Promise<Record<string, string[]> | undefined>;
+/**
+ * Calculate Levenshtein distance between two strings.
+ * Used for suggesting similar agent names for typos.
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Warn about unknown agent names in fragments config.
+ * Suggests similar valid agent names for likely typos.
+ */
+export declare function warnUnknownAgents(fragments: Record<string, string[]> | undefined): void;
+export interface FragmentInjectorContext {
+    projectDir: string;
+}
+/**
+ * Create a fragment injector that can modify agent system prompts.
+ * Returns merged fragments from global config and project config.
+ */
+export declare function createFragmentInjector(ctx: FragmentInjectorContext, globalFragments: FragmentsRecord): Promise<Record<string, string[]>>;
+/**
+ * Get the system prompt prefix for a specific agent.
+ */
+export declare function getAgentSystemPromptPrefix(fragments: Record<string, string[]>, agentName: string): string;
+export {};

package/dist/hooks/index.d.ts

@@ -0,0 +1 @@
+export { createFragmentInjector, type FragmentInjectorContext, formatFragmentsBlock, getAgentSystemPromptPrefix, levenshteinDistance, loadProjectFragments, mergeFragments, warnUnknownAgents, } from "./fragment-injector";

package/dist/index.js

@@ -509,6 +509,58 @@ function getFallback(schema, dataset, config$1) {
 function getDefault(schema, dataset, config$1) {
   return typeof schema.default === "function" ? schema.default(dataset, config$1) : schema.default;
 }
+function array(item, message$1) {
+  return {
+    kind: "schema",
+    type: "array",
+    reference: array,
+    expects: "Array",
+    async: false,
+    item,
+    message: message$1,
+    get "~standard"() {
+      return /* @__PURE__ */ _getStandardProps(this);
+    },
+    "~run"(dataset, config$1) {
+      const input = dataset.value;
+      if (Array.isArray(input)) {
+        dataset.typed = true;
+        dataset.value = [];
+        for (let key = 0;key < input.length; key++) {
+          const value$1 = input[key];
+          const itemDataset = this.item["~run"]({ value: value$1 }, config$1);
+          if (itemDataset.issues) {
+            const pathItem = {
+              type: "array",
+              origin: "value",
+              input,
+              key,
+              value: value$1
+            };
+            for (const issue of itemDataset.issues) {
+              if (issue.path)
+                issue.path.unshift(pathItem);
+              else
+                issue.path = [pathItem];
+              dataset.issues?.push(issue);
+            }
+            if (!dataset.issues)
+              dataset.issues = itemDataset.issues;
+            if (config$1.abortEarly) {
+              dataset.typed = false;
+              break;
+            }
+          }
+          if (!itemDataset.typed)
+            dataset.typed = false;
+          dataset.value.push(itemDataset.value);
+        }
+      } else
+        _addIssue(this, "type", dataset, config$1);
+      return dataset;
+    }
+  };
+}
 function enum_(enum__, message$1) {
   const options = [];
   for (const key in enum__)
@@ -795,11 +847,27 @@ 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 FragmentsSchema = optional(record(enum_(AGENTS), array(string())));
 var OcttoConfigSchema = object({
-  agents: optional(record(enum_(AGENTS), AgentOverrideSchema))
+  agents: optional(record(enum_(AGENTS), AgentOverrideSchema)),
+  port: optional(PortSchema),
+  fragments: FragmentsSchema
 });
 
 // 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,15 +926,125 @@ async function load(configDir) {
 }
 async function loadCustomConfig(agents2, configDir) {
   const config = await load(configDir);
-  if (!config?.agents) {
-    return agents2;
+  const mergedAgents = { ...agents2 };
+  if (config?.agents) {
+    for (const [name, override] of Object.entries(config.agents)) {
+      mergedAgents[name] = { ...agents2[name], ...override };
+    }
+  }
+  return {
+    agents: mergedAgents,
+    port: resolvePort(config?.port),
+    fragments: config?.fragments
+  };
+}
+// src/hooks/fragment-injector.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join2 } from "path";
+var VALID_AGENT_NAMES2 = Object.values(AGENTS);
+var ProjectFragmentsSchema = record(string(), array(string()));
+function formatFragmentsBlock(fragments) {
+  if (!fragments || fragments.length === 0) {
+    return "";
+  }
+  const bulletPoints = fragments.map((f) => `- ${f}`).join(`
+`);
+  return `<user-instructions>
+${bulletPoints}
+</user-instructions>
+
+`;
+}
+function mergeFragments(global, project) {
+  const result = {};
+  if (global) {
+    for (const [agent4, frags] of Object.entries(global)) {
+      result[agent4] = [...frags];
+    }
   }
-  const result = { ...agents2 };
-  for (const [name, override] of Object.entries(config.agents)) {
-    result[name] = { ...agents2[name], ...override };
+  if (project) {
+    for (const [agent4, frags] of Object.entries(project)) {
+      if (result[agent4]) {
+        result[agent4].push(...frags);
+      } else {
+        result[agent4] = [...frags];
+      }
+    }
   }
   return result;
 }
+async function loadProjectFragments(projectDir) {
+  const fragmentsPath = join2(projectDir, ".octto", "fragments.json");
+  try {
+    const content = await readFile2(fragmentsPath, "utf-8");
+    const parsed = JSON.parse(content);
+    const result = safeParse(ProjectFragmentsSchema, parsed);
+    if (!result.success) {
+      console.warn(`[octto] Invalid fragments.json schema in ${fragmentsPath}`);
+      return;
+    }
+    return result.output;
+  } catch {
+    return;
+  }
+}
+function levenshteinDistance(a, b) {
+  if (a.length === 0)
+    return b.length;
+  if (b.length === 0)
+    return a.length;
+  const matrix = [];
+  for (let i = 0;i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0;j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1;i <= b.length; i++) {
+    for (let j = 1;j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+      }
+    }
+  }
+  return matrix[b.length][a.length];
+}
+function warnUnknownAgents(fragments) {
+  if (!fragments)
+    return;
+  for (const agentName of Object.keys(fragments)) {
+    if (VALID_AGENT_NAMES2.includes(agentName)) {
+      continue;
+    }
+    let closest;
+    let minDistance = Infinity;
+    for (const validName of VALID_AGENT_NAMES2) {
+      const distance = levenshteinDistance(agentName, validName);
+      if (distance < minDistance && distance <= 3) {
+        minDistance = distance;
+        closest = validName;
+      }
+    }
+    let message = `[octto] Unknown agent "${agentName}" in fragments config.`;
+    if (closest) {
+      message += ` Did you mean "${closest}"?`;
+    }
+    message += ` Valid agents: ${VALID_AGENT_NAMES2.join(", ")}`;
+    console.warn(message);
+  }
+}
+async function createFragmentInjector(ctx, globalFragments) {
+  const projectFragments = await loadProjectFragments(ctx.projectDir);
+  const merged = mergeFragments(globalFragments, projectFragments);
+  warnUnknownAgents(globalFragments);
+  warnUnknownAgents(projectFragments);
+  return merged;
+}
+function getAgentSystemPromptPrefix(fragments, agentName) {
+  return formatFragmentsBlock(fragments[agentName]);
+}
 // src/constants.ts
 var DEFAULT_ANSWER_TIMEOUT_MS = 300000;
 
@@ -2504,10 +2682,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 +2843,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,
@@ -3085,7 +3263,7 @@ __export(exports_external, {
   bigint: () => bigint2,
   base64url: () => base64url2,
   base64: () => base642,
-  array: () => array,
+  array: () => array2,
   any: () => any,
   _function: () => _function,
   _default: () => _default2,
@@ -3581,8 +3759,8 @@ function getEnumValues(entries) {
   const values = Object.entries(entries).filter(([k, _]) => numericValues.indexOf(+k) === -1).map(([_, v]) => v);
   return values;
 }
-function joinValues(array, separator = "|") {
-  return array.map((val) => stringifyPrimitive(val)).join(separator);
+function joinValues(array2, separator = "|") {
+  return array2.map((val) => stringifyPrimitive(val)).join(separator);
 }
 function jsonStringifyReplacer(_, value) {
   if (typeof value === "bigint")
@@ -14270,7 +14448,7 @@ var ZodType = /* @__PURE__ */ $constructor("ZodType", (inst, def) => {
   inst.nullable = () => nullable(inst);
   inst.nullish = () => optional2(nullable(inst));
   inst.nonoptional = (params) => nonoptional(inst, params);
-  inst.array = () => array(inst);
+  inst.array = () => array2(inst);
   inst.or = (arg) => union([inst, arg]);
   inst.and = (arg) => intersection(inst, arg);
   inst.transform = (tx) => pipe2(inst, transform(tx));
@@ -14691,7 +14869,7 @@ var ZodArray = /* @__PURE__ */ $constructor("ZodArray", (inst, def) => {
   inst.length = (len, params) => inst.check(_length(len, params));
   inst.unwrap = () => inst.element;
 });
-function array(element, params) {
+function array2(element, params) {
   return _array(ZodArray, element, params);
 }
 function keyof(schema) {
@@ -15153,7 +15331,7 @@ var ZodFunction = /* @__PURE__ */ $constructor("ZodFunction", (inst, def) => {
 function _function(params) {
   return new ZodFunction({
     type: "function",
-    input: Array.isArray(params?.input) ? tuple(params?.input) : params?.input ?? array(unknown()),
+    input: Array.isArray(params?.input) ? tuple(params?.input) : params?.input ?? array2(unknown()),
     output: params?.output ?? unknown()
   });
 }
@@ -15197,7 +15375,7 @@ var stringbool = (...args) => _stringbool({
 }, ...args);
 function json(params) {
   const jsonSchema = lazy(() => {
-    return union([string3(params), number3(), boolean2(), _null3(), array(jsonSchema), record2(string3(), jsonSchema)]);
+    return union([string3(params), number3(), boolean2(), _null3(), array2(jsonSchema), record2(string3(), jsonSchema)]);
   });
   return jsonSchema;
 }
@@ -15263,7 +15441,7 @@ tool.schema = exports_external;
 
 // src/state/persistence.ts
 import { existsSync, mkdirSync, readdirSync, rmSync } from "fs";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 function validateSessionId(sessionId) {
   if (!/^[a-zA-Z0-9_-]+$/.test(sessionId)) {
     throw new Error(`Invalid session ID: ${sessionId}`);
@@ -15272,7 +15450,7 @@ function validateSessionId(sessionId) {
 function createStatePersistence(baseDir = ".brainstorm") {
   function getFilePath(sessionId) {
     validateSessionId(sessionId);
-    return join2(baseDir, `${sessionId}.json`);
+    return join3(baseDir, `${sessionId}.json`);
   }
   function ensureDir() {
     if (!existsSync(baseDir)) {
@@ -16523,9 +16701,17 @@ function createOcttoTools(sessions, client) {
 }
 
 // src/index.ts
-var Octto = async ({ client }) => {
+var Octto = async ({ client, directory }) => {
   const customConfig = await loadCustomConfig(agents);
-  const sessions = createSessionStore();
+  const fragments = await createFragmentInjector({ projectDir: directory }, customConfig.fragments);
+  for (const agentName of Object.values(AGENTS)) {
+    const prefix = getAgentSystemPromptPrefix(fragments, agentName);
+    if (prefix && customConfig.agents[agentName]?.prompt) {
+      customConfig.agents[agentName].prompt = prefix + customConfig.agents[agentName].prompt;
+    }
+  }
+  warnUnknownAgents(customConfig.fragments);
+  const sessions = createSessionStore({ port: customConfig.port });
   const tracked = new Map;
   const tools = createOcttoTools(sessions, client);
   const originalExecute = tools.start_session.execute;
@@ -16543,7 +16729,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.3.0",
   "description": "OpenCode plugin that turns rough ideas into designs through branch-based exploration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",