Skip to content

armgit / Orkas

Public Imported from GitHub
0

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.

Return actionable project instruction length failures

wyt62da1caeab0f
diff --git a/bin/orkas-bridge.cjs b/bin/orkas-bridge.cjs
index 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.cjs
new file mode 100644
index 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.cts
new file mode 100644
index 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.ts
index 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: ProjectInstructionsToolHa
properties: {
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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 stdio
expect(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 stdio
const 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 stdio
const 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.ts
index 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');