Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.
JavaScript agent-collaborationagent-harnessagent-orchestrationagent-teamagent-workflowai-assistantai-automationai-employeeai-productivityai-teamai-workflowautonomous-agentsclaude-code-guiclaude-coworkdesktop-agentlocal-firstmulti-agentmulti-agent-systemself-evolving-agentstask-automation
Return actionable project instruction length failures
wyt62da1caeab0f
diff --git a/bin/orkas-bridge.cjs b/bin/orkas-bridge.cjsindex 0a3c126a..69e01a72 100644--- a/bin/orkas-bridge.cjs+++ b/bin/orkas-bridge.cjs@@ -36,6 +36,7 @@'use strict';const { defaultNumericRange } = require('./tool-input-compat.cjs');+const { PROJECT_INSTRUCTIONS_TEXT_DESCRIPTION } = require('./project-instructions-contract.cjs');const path = require('node:path');const fs = require('node:fs');@@ -524,7 +525,8 @@ function createServer() {server.registerTool('project_instructions', ...bridgeToolInput(z,'Replace the current project standing instructions with the complete text. Preserve applicable existing rules; concurrent changes return a conflict.',- { instructions: z.string().min(1).max(4000).describe('Complete replacement goal and rules text.') },+ // The host enforces UTF-16 length and returns limit/actual without clipping.+ { instructions: z.string().min(1).describe(PROJECT_INSTRUCTIONS_TEXT_DESCRIPTION) },async (params) => {try { return projectWriteResult(await rpc('project_instructions', params)); }catch (err) { return errorResult(err); }diff --git a/bin/project-instructions-contract.cjs b/bin/project-instructions-contract.cjsnew file mode 100644index 00000000..a4dae5d8--- /dev/null+++ b/bin/project-instructions-contract.cjs@@ -0,0 +1,8 @@+'use strict';++// Shared by native tools, the MCP bridge and the authoritative host writer.+const PROJECT_INSTRUCTIONS_CHAR_LIMIT = 4000;+const PROJECT_INSTRUCTIONS_TEXT_DESCRIPTION =+ `Complete replacement goal/rules text, including any existing content that still applies. Maximum ${PROJECT_INSTRUCTIONS_CHAR_LIMIT} UTF-16 code units; a supplementary Unicode character counts as two.`;++module.exports = { PROJECT_INSTRUCTIONS_CHAR_LIMIT, PROJECT_INSTRUCTIONS_TEXT_DESCRIPTION };diff --git a/bin/project-instructions-contract.d.cts b/bin/project-instructions-contract.d.ctsnew file mode 100644index 00000000..bb4cef8b--- /dev/null+++ b/bin/project-instructions-contract.d.cts@@ -0,0 +1,2 @@+export const PROJECT_INSTRUCTIONS_CHAR_LIMIT: 4000;+export const PROJECT_INSTRUCTIONS_TEXT_DESCRIPTION: string;diff --git a/src/core-agent/src/tools/project-instructions-tool.ts b/src/core-agent/src/tools/project-instructions-tool.tsindex fbade745..a003ec17 100644--- a/src/core-agent/src/tools/project-instructions-tool.ts+++ b/src/core-agent/src/tools/project-instructions-tool.ts@@ -14,10 +14,11 @@*/import type { AgentTool, ToolContext, ToolResult } from "./base.js";+import { PROJECT_INSTRUCTIONS_TEXT_DESCRIPTION } from '../../../../bin/project-instructions-contract.cjs';export interface ProjectInstructionsToolHandler {/** Replace the project's instructions with `instructions` (full content). */- set(instructions: string): Promise<{ ok: boolean; error?: string }>;+ set(instructions: string): Promise<{ ok: boolean; error?: string; limit?: number; actual?: number }>;}const TOOL_DESCRIPTION =@@ -32,7 +33,7 @@ export function createProjectInstructionsTool(handler: ProjectInstructionsToolHaproperties: {instructions: {type: 'string',- description: 'Complete replacement goal/rules text, including any existing content that still applies.',+ description: PROJECT_INSTRUCTIONS_TEXT_DESCRIPTION,},},required: ['instructions'],diff --git a/src/core-agent/test/project-instructions-tool.test.ts b/src/core-agent/test/project-instructions-tool.test.tsindex 41608a05..88a962ae 100644--- a/src/core-agent/test/project-instructions-tool.test.ts+++ b/src/core-agent/test/project-instructions-tool.test.ts@@ -30,6 +30,8 @@ describe('project_instructions tool', () => {expect(def.description).toContain('project memory');expect(instructions.description).toContain('Complete replacement');expect(instructions.description).toContain('existing content that still applies');+ expect(instructions.description).toContain('4000 UTF-16 code units');+ expect(instructions.maxLength).toBeUndefined(); // JSON Schema counts code points.});it('dispatches to handler.set with the full content', async () => {diff --git a/src/main/features/projects.ts b/src/main/features/projects.tsindex a29b5f02..bc79fd11 100644--- a/src/main/features/projects.ts+++ b/src/main/features/projects.ts@@ -55,6 +55,7 @@ import * as autoTasks from './auto_tasks';import { readState } from './group_chat/state';import { purgeProjectWorkspace } from './user_workspace';import { limitNameDisplayText } from '../util/name-limit';+import { PROJECT_INSTRUCTIONS_CHAR_LIMIT } from '../../../bin/project-instructions-contract.cjs';const log = createLogger('projects');@@ -460,7 +461,7 @@ export async function renameProjectForUser(uid: string, projectId: string, name:// and named project actors can replace it via `project_instructions` using// the conditional writer.-export const PROJECT_INSTRUCTIONS_CHAR_LIMIT = 4000;+export { PROJECT_INSTRUCTIONS_CHAR_LIMIT };/** Static conflict core shared by every project-aware model surface. */export function formatProjectContextCoreForPrompt(): string {@@ -512,8 +513,10 @@ export async function writeProjectInstructions(uid: string,projectId: string,content: string,-): Promise<{ ok: true } | { ok: false; error: ProjectError }> {- if (content.length > PROJECT_INSTRUCTIONS_CHAR_LIMIT) return { ok: false, error: 'too_long' };+): Promise<{ ok: true } | { ok: false; error: ProjectError; limit?: number; actual?: number }> {+ if (content.length > PROJECT_INSTRUCTIONS_CHAR_LIMIT) {+ return { ok: false, error: 'too_long', limit: PROJECT_INSTRUCTIONS_CHAR_LIMIT, actual: content.length };+ }return withProjectInstructionsMutationLock(uid, projectId, async () => {const cur = await _readProject(uid, projectId);if (!cur) return { ok: false, error: 'not_found' };@@ -541,8 +544,10 @@ export async function writeProjectInstructionsIfUnchanged(projectId: string,expectedContent: string,content: string,-): Promise<{ ok: true } | { ok: false; error: ProjectInstructionsConditionalWriteError }> {- if (content.length > PROJECT_INSTRUCTIONS_CHAR_LIMIT) return { ok: false, error: 'too_long' };+): Promise<{ ok: true } | { ok: false; error: ProjectInstructionsConditionalWriteError; limit?: number; actual?: number }> {+ if (content.length > PROJECT_INSTRUCTIONS_CHAR_LIMIT) {+ return { ok: false, error: 'too_long', limit: PROJECT_INSTRUCTIONS_CHAR_LIMIT, actual: content.length };+ }return withProjectInstructionsMutationLock(uid, projectId, async () => {const cur = await _readProject(uid, projectId);if (!cur) return { ok: false, error: 'not_found' };diff --git a/src/main/model/core-agent/runner.ts b/src/main/model/core-agent/runner.tsindex 79afab4f..329f8a36 100644--- a/src/main/model/core-agent/runner.ts+++ b/src/main/model/core-agent/runner.ts@@ -782,7 +782,7 @@ export async function buildRunner(params: BuildRunnerParams): Promise<{const error = writeError === 'conflict'? 'conflict: project instructions changed after this turn started; retry in a new turn with the latest content': writeError;- return { ok: false, error };+ return { ...r, ok: false, error };},}));}diff --git a/src/main/model/core-agent/tool-catalog-revision.ts b/src/main/model/core-agent/tool-catalog-revision.tsindex 5879d208..9b9c7544 100644--- a/src/main/model/core-agent/tool-catalog-revision.ts+++ b/src/main/model/core-agent/tool-catalog-revision.ts@@ -5,4 +5,4 @@* it as their current-state oracle without pulling the Electron runtime or the* tool catalog's logger/path dependency chain into model-eval processes.*/-export const TOOL_CATALOG_REVISION = '81';+export const TOOL_CATALOG_REVISION = '84';diff --git a/test/main/features/local_agents/bridge_e2e.test.ts b/test/main/features/local_agents/bridge_e2e.test.tsindex f57adc40..05c30df2 100644--- a/test/main/features/local_agents/bridge_e2e.test.ts+++ b/test/main/features/local_agents/bridge_e2e.test.ts@@ -1195,6 +1195,15 @@ describe.each(['legacy', 'modern'] as const)('orkas-bridge.cjs › %s MCP stdioexpect(JSON.parse(updated.content.at(-1).text)).toEqual({ ignored_fields: ['future_option'] });expect(JSON.stringify(updated)).not.toContain('PRIVATE_VALUE');expect(await projects.readProjectInstructions(TEST_UID, pid)).toMatchObject({ content: 'Keep delivery accessible.' });+ const instructionsSchema = listed.result.tools.find((tool: any) => tool.name === 'project_instructions').inputSchema.properties.instructions;+ expect(instructionsSchema.description).toContain('4000 UTF-16 code units');+ expect(instructionsSchema.maxLength).toBeUndefined();+ const tooLong = await call('project_instructions', { instructions: '😀'.repeat(2000) + 'x' });+ expect(tooLong.isError).toBe(true);+ expect(JSON.parse(tooLong.content[0].text)).toEqual({ ok: false, error: 'too_long', limit: 4000, actual: 4001 });+ expect(await projects.readProjectInstructions(TEST_UID, pid)).toMatchObject({ content: 'Keep delivery accessible.' });+ expect((await call('project_instructions', { instructions: 'Corrected replacement.' })).isError).toBeFalsy();+ expect(await projects.readProjectInstructions(TEST_UID, pid)).toMatchObject({ content: 'Corrected replacement.' });expect((await call('cross_session_memory', { action: 'add', target: 'project', content: 'The audience uses keyboards.' })).isError).toBeFalsy();expect(memory.listEntries(TEST_UID, { project: pid }).entries).toEqual(['The audience uses keyboards.']);const rejected = await call('library_save', { source_path: 'deliverable.md', expected_revision: '' });@@ -1248,11 +1257,11 @@ describe.each(['legacy', 'modern'] as const)('orkas-bridge.cjs › %s MCP stdioconst runner = built.runner as unknown as {activeTools(): Array<{ name: string; execute(input: Record<string, unknown>, ctx: unknown): Promise<{ content: string; isError?: boolean }> }>;};- return async (name: string, input: Record<string, unknown>) => {+ return async (name: string, input: Record<string, unknown>, expectError = false) => {const tool = runner.activeTools().find((entry) => entry.name === name);expect(tool, `native turn must expose ${name}`).toBeDefined();const result = await tool!.execute(input, { workingDir: tmpDir, state: {} });- expect(result.isError, result.content).toBeFalsy();+ expect(Boolean(result.isError), result.content).toBe(expectError);return JSON.parse(result.content);};};@@ -1260,6 +1269,9 @@ describe.each(['legacy', 'modern'] as const)('orkas-bridge.cjs › %s MCP stdioconst initialRules = 'Preserve keyboard access.';const initialFact = 'The supported locale is English.';await native('project_instructions', { instructions: initialRules });+ expect(await native('project_instructions', { instructions: '😀'.repeat(2000) + 'x' }, true))+ .toEqual({ ok: false, error: 'too_long', limit: 4000, actual: 4001 });+ expect(await projects.readProjectInstructions(TEST_UID, pid)).toMatchObject({ content: initialRules });await native('cross_session_memory', { action: 'add', target: 'project', content: initialFact });await native('cross_session_memory', { action: 'add', target: 'agent', content: 'Native private note.' });fs.writeFileSync(path.join(tmpDir, 'shared.md'), 'Native draft.');diff --git a/test/main/features/projects.test.ts b/test/main/features/projects.test.tsindex 18d9dce9..096884c8 100644--- a/test/main/features/projects.test.ts+++ b/test/main/features/projects.test.ts@@ -801,13 +801,34 @@ describe('projects › instructions', () => {if (!r.ok) throw new Error('create failed');const over = await projects.writeProjectInstructions(TEST_UID, r.project.project_id, 'x'.repeat(projects.PROJECT_INSTRUCTIONS_CHAR_LIMIT + 1));- expect(over).toEqual({ ok: false, error: 'too_long' });+ expect(over).toEqual({ ok: false, error: 'too_long', limit: 4000, actual: 4001 });// at-limit content is accepted (boundary)const atLimit = await projects.writeProjectInstructions(TEST_UID, r.project.project_id, 'x'.repeat(projects.PROJECT_INSTRUCTIONS_CHAR_LIMIT));expect(atLimit.ok).toBe(true);});+ it.each(['x', '中', '😀'])('preserves content on an over-limit %s write and accepts a corrected replacement', async (unit) => {+ const projects = await loadProjects();+ const created = await projects.createProject(TEST_UID, 'Length recovery');+ if (!created.ok) throw new Error('fixture failed');+ const pid = created.project.project_id;+ const atLimit = unit.repeat(4000 / unit.length);+ const overLimit = atLimit + 'x';+ expect(await projects.writeProjectInstructions(TEST_UID, pid, 'Original')).toEqual({ ok: true });+ for (const conditional of [false, true]) {+ const result = conditional+ ? await projects.writeProjectInstructionsIfUnchanged(TEST_UID, pid, 'Original', overLimit)+ : await projects.writeProjectInstructions(TEST_UID, pid, overLimit);+ expect(result).toEqual({ ok: false, error: 'too_long', limit: 4000, actual: 4001 });+ expect(await projects.readProjectInstructions(TEST_UID, pid)).toMatchObject({ content: 'Original' });+ }+ expect(await projects.writeProjectInstructionsIfUnchanged(TEST_UID, pid, 'Original', atLimit)).toEqual({ ok: true });+ expect(await projects.readProjectInstructions(TEST_UID, pid)).toMatchObject({ content: atLimit });+ expect(await projects.writeProjectInstructionsIfUnchanged(TEST_UID, pid, 'Original', 'Stale')).toEqual({ ok: false, error: 'conflict' });+ expect(await projects.readProjectInstructions(TEST_UID, pid)).toMatchObject({ content: atLimit });+ });+it('formatProjectInstructionsForSystemPrompt: block for real content, empty for missing/blank', async () => {const projects = await loadProjects();const r = await projects.createProject(TEST_UID, 'P');