octto 0.2.0 → 0.3.0

package/README.md

@@ -117,6 +117,34 @@ Optional `~/.config/opencode/octto.json`:
 |--------|------|---------|-------------|
 | `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
 

package/dist/config/index.d.ts

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

package/dist/config/loader.d.ts

@@ -1,6 +1,7 @@
 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)
@@ -9,6 +10,7 @@ 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.

package/dist/config/schema.d.ts

@@ -39,6 +39,7 @@ export declare const AgentOverrideSchema: Omit<v.ObjectSchema<{
     } | 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>;
@@ -79,6 +80,8 @@ export declare const OcttoConfigSchema: v.ObjectSchema<{
         } | 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__)
@@ -796,9 +848,11 @@ var AgentOverrideSchema = partial(object({
   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)),
-  port: optional(PortSchema)
+  port: optional(PortSchema),
+  fragments: FragmentsSchema
 });
 
 // src/config/loader.ts
@@ -880,9 +934,117 @@ async function loadCustomConfig(agents2, configDir) {
   }
   return {
     agents: mergedAgents,
-    port: resolvePort(config?.port)
+    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];
+    }
+  }
+  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;
 
@@ -3101,7 +3263,7 @@ __export(exports_external, {
   bigint: () => bigint2,
   base64url: () => base64url2,
   base64: () => base642,
-  array: () => array,
+  array: () => array2,
   any: () => any,
   _function: () => _function,
   _default: () => _default2,
@@ -3597,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")
@@ -14286,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));
@@ -14707,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) {
@@ -15169,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()
   });
 }
@@ -15213,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;
 }
@@ -15279,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}`);
@@ -15288,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)) {
@@ -16539,8 +16701,16 @@ function createOcttoTools(sessions, client) {
 }
 
 // src/index.ts
-var Octto = async ({ client }) => {
+var Octto = async ({ client, directory }) => {
   const customConfig = await loadCustomConfig(agents);
+  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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octto",
-  "version": "0.2.0",
+  "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",