khabotcli 1.0.0

package/test/integration/10-task-advanced.test.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// ── Test 10: Advanced task operations ─────────────────────────────────────────
+
+await test('Task cancellation works', async () => {
+  // Create a task, immediately cancel it before it can finish
+  const res = await client.tasks.create('hello',
+    'Count very slowly from 1 to 1000, saying each number with a pause.'
+  );
+  assert.strictEqual(res.status, 202);
+  const { taskId } = res.body;
+
+  // Give it a moment to start, then cancel
+  await new Promise(r => setTimeout(r, 500));
+  const cancelRes = await client.tasks.cancel(taskId);
+  assert.strictEqual(cancelRes.status, 200, JSON.stringify(cancelRes.body));
+  assert.strictEqual(cancelRes.body.status, 'canceled');
+
+  // Verify final state
+  const getRes = await client.tasks.get(taskId);
+  assert(['canceled', 'finished'].includes(getRes.body.task.status),
+    `Expected canceled or finished (if it finished first), got: ${getRes.body.task.status}`);
+});
+
+await test('Multiple concurrent tasks run independently', async () => {
+  // Launch 3 tasks simultaneously
+  const [r1, r2, r3] = await Promise.all([
+    client.tasks.create('hello', 'What is 10 + 5? Reply with just the number.'),
+    client.tasks.create('hello', 'What is 20 + 3? Reply with just the number.'),
+    client.tasks.create('hello', 'What is 7 + 8? Reply with just the number.'),
+  ]);
+
+  assert.strictEqual(r1.status, 202);
+  assert.strictEqual(r2.status, 202);
+  assert.strictEqual(r3.status, 202);
+
+  // All different task IDs
+  const ids = [r1.body.taskId, r2.body.taskId, r3.body.taskId];
+  assert.strictEqual(new Set(ids).size, 3, 'All taskIds should be unique');
+
+  // Poll all to completion
+  const [t1, t2, t3] = await Promise.all([
+    client.pollTask(r1.body.taskId, { timeout: 90000 }),
+    client.pollTask(r2.body.taskId, { timeout: 90000 }),
+    client.pollTask(r3.body.taskId, { timeout: 90000 }),
+  ]);
+
+  assert.strictEqual(t1.status, 'finished', `Task 1 failed: ${t1.error}`);
+  assert.strictEqual(t2.status, 'finished', `Task 2 failed: ${t2.error}`);
+  assert.strictEqual(t3.status, 'finished', `Task 3 failed: ${t3.error}`);
+
+  assert(String(t1.output || '').includes('15'), `Task 1: expected 15 in output, got: ${t1.output}`);
+  assert(String(t2.output || '').includes('23'), `Task 2: expected 23 in output, got: ${t2.output}`);
+  assert(String(t3.output || '').includes('15'), `Task 3: expected 15 in output, got: ${t3.output}`);
+}, { slow: true });
+
+await test('Task list filtering by agent works', async () => {
+  // Create a task for hello agent
+  await client.tasks.create('hello', 'Say: FILTER_TEST');
+  // Give it a moment
+  await new Promise(r => setTimeout(r, 300));
+
+  const res = await client.tasks.list({ agentName: 'hello', limit: 5 });
+  assert.strictEqual(res.status, 200);
+  const allHello = res.body.tasks.every(t => t.agent_name === 'hello');
+  assert(allHello, 'All tasks should be from hello agent');
+});
+
+await test('Task list filtering by status works', async () => {
+  const res = await client.tasks.list({ status: 'finished', limit: 10 });
+  assert.strictEqual(res.status, 200);
+  const allFinished = res.body.tasks.every(t => t.status === 'finished');
+  assert(allFinished, 'All returned tasks should be finished');
+});
+
+await test('Task respond returns 400 when task is not waiting', async () => {
+  // Create a task that completes quickly
+  const createRes = await client.tasks.create('hello', 'Say: RESPOND_TEST');
+  const task = await client.pollTask(createRes.body.taskId, { timeout: 60000 });
+
+  // Try to respond to a finished task
+  const respondRes = await client.tasks.respond(task.id, 'Some response');
+  assert.strictEqual(respondRes.status, 400);
+  assert.strictEqual(respondRes.body.error.code, 'TASK_NOT_WAITING');
+}, { slow: true });

package/test/integration/11-sessions-advanced.test.js

@@ -0,0 +1,84 @@
+'use strict';
+
+// ── Test 11: Advanced session management ──────────────────────────────────────
+
+await test('GET /sessions/:id returns correct session data', async () => {
+  const chatRes = await client.chat.send('hello', 'Session data test.');
+  assert.strictEqual(chatRes.status, 200);
+  const { sessionId } = chatRes.body;
+
+  const res = await client.sessions.get(sessionId);
+  assert.strictEqual(res.status, 200, JSON.stringify(res.body));
+  const { session } = res.body;
+  assert.strictEqual(session.id, sessionId);
+  assert.strictEqual(session.agent_name, 'hello');
+  assert.strictEqual(session.mode, 'chat');
+  assert.strictEqual(session.status, 'active');
+  assert(session.message_count >= 2, `Expected ≥2 messages, got: ${session.message_count}`);
+  assert(session.token_input > 0, 'token_input should be > 0');
+  assert(session.token_output > 0, 'token_output should be > 0');
+});
+
+await test('GET /sessions/:id/messages paginates correctly', async () => {
+  // Create a session with multiple exchanges
+  const chatRes = await client.chat.send('hello', 'Message 1: Alpha');
+  const { sessionId } = chatRes.body;
+  await client.chat.send('hello', 'Message 2: Beta', sessionId);
+  await client.chat.send('hello', 'Message 3: Gamma', sessionId);
+
+  // Get all messages
+  const res = await client.sessions.messages(sessionId);
+  assert.strictEqual(res.status, 200);
+  assert(res.body.messages.length >= 7, `Expected ≥7 messages (system + 3 user + 3 assistant), got: ${res.body.messages.length}`);
+
+  // Test with limit
+  const limitRes = await fetch(`http://localhost:5050/sessions/${sessionId}/messages?limit=3`);
+  const limitBody = await limitRes.json();
+  assert(limitBody.messages.length <= 3, `Limit should cap at 3, got: ${limitBody.messages.length}`);
+}, { slow: true });
+
+await test('DELETE /sessions/:id closes the session', async () => {
+  const chatRes = await client.chat.send('hello', 'Close me.');
+  const { sessionId } = chatRes.body;
+
+  // Verify it's active
+  const beforeRes = await client.sessions.get(sessionId);
+  assert.strictEqual(beforeRes.body.session.status, 'active');
+
+  // Close it
+  const delRes = await fetch(`http://localhost:5050/sessions/${sessionId}`, { method: 'DELETE' });
+  assert.strictEqual(delRes.status, 200);
+  const delBody = await delRes.json();
+  assert.strictEqual(delBody.status, 'closed');
+
+  // Verify it's closed
+  const afterRes = await client.sessions.get(sessionId);
+  assert.strictEqual(afterRes.body.session.status, 'closed');
+});
+
+await test('GET /sessions/:id returns 404 for unknown session', async () => {
+  const res = await client.sessions.get('sess_nonexistent_xyz_123');
+  assert.strictEqual(res.status, 404);
+  assert.strictEqual(res.body.error.code, 'SESSION_NOT_FOUND');
+});
+
+await test('Consecutive multi-turn chat builds coherent context', async () => {
+  // Turn 1: set context
+  const r1 = await client.chat.send('hello', 'I am testing KhaBotCLI. Remember: codeword = ZEBRA_KITE_77.');
+  const { sessionId } = r1.body;
+
+  // Turn 2: verify context
+  const r2 = await client.chat.send('hello', 'What codeword did I give you?', sessionId);
+  assert(
+    r2.body.message.content.includes('ZEBRA_KITE_77'),
+    `Expected codeword in response, got: ${r2.body.message.content}`
+  );
+
+  // Turn 3: follow-up question showing context chain
+  const r3 = await client.chat.send('hello', 'Good. Now repeat the codeword backwards letter by letter would be complex, just confirm it starts with Z.', sessionId);
+  const content = r3.body.message.content.toLowerCase();
+  assert(
+    content.includes('z') || content.includes('zebra') || content.includes('yes'),
+    `Expected confirmation with Z, got: ${r3.body.message.content}`
+  );
+}, { slow: true });

package/test/integration/12-assistant-chat-tools.test.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// ── Test 12: Assistant agent chat mode with tool use ──────────────────────────
+
+const path = require('path');
+const PROJECT_ROOT = path.join(__dirname, '../..');
+
+await test('Assistant chat: uses read_file to answer a question', async () => {
+  const res = await client.chat.send('assistant',
+    `What is the "version" field in the file ${PROJECT_ROOT}/package.json? Use the read_file tool.`
+  );
+  assert.strictEqual(res.status, 200, JSON.stringify(res.body));
+  const content = res.body.message.content;
+  assert(
+    content.includes('0.1.0') || content.includes('version'),
+    `Expected version in response, got: ${content}`
+  );
+});
+
+await test('Assistant chat: uses list_dir to explore a directory', async () => {
+  const res = await client.chat.send('assistant',
+    `Use list_dir to show me what's in ${PROJECT_ROOT}/core. Just list the filenames.`
+  );
+  assert.strictEqual(res.status, 200, JSON.stringify(res.body));
+  const content = res.body.message.content;
+  assert(
+    content.includes('agent.js') || content.includes('loop.js') || content.includes('prompt.js'),
+    `Expected core/ files listed, got: ${content}`
+  );
+});
+
+await test('Assistant chat: uses bash to run a simple command', async () => {
+  const res = await client.chat.send('assistant',
+    `Run the bash command: echo "BASH_CHAT_TEST_$(date +%Y)" and tell me the output.`
+  );
+  assert.strictEqual(res.status, 200, JSON.stringify(res.body));
+  const content = res.body.message.content;
+  const year = new Date().getFullYear().toString();
+  assert(
+    content.includes(year) || content.includes('BASH_CHAT_TEST'),
+    `Expected year ${year} or BASH_CHAT_TEST in response, got: ${content}`
+  );
+});
+
+await test('Assistant chat: uses grep to search across files', async () => {
+  const res = await client.chat.send('assistant',
+    `Use grep to find all files in ${PROJECT_ROOT}/core that contain the word "permission". List the matching files.`
+  );
+  assert.strictEqual(res.status, 200, JSON.stringify(res.body));
+  const content = res.body.message.content;
+  // loop.js contains "permission"
+  assert(
+    content.includes('loop.js') || content.includes('core/') || content.includes('permission'),
+    `Expected grep results mentioning loop.js or core files, got: ${content}`
+  );
+});
+
+await test('Assistant chat: multi-turn with tool context', async () => {
+  const r1 = await client.chat.send('assistant',
+    `Read ${PROJECT_ROOT}/utils/id.js and tell me the function name that generates IDs.`
+  );
+  assert.strictEqual(r1.status, 200);
+  const { sessionId } = r1.body;
+
+  const r2 = await client.chat.send('assistant',
+    `In the same file, what prefix parameter does that function accept? Look at the function signature.`,
+    sessionId
+  );
+  assert.strictEqual(r2.status, 200);
+  const content = r2.body.message.content.toLowerCase();
+  assert(
+    content.includes('prefix') || content.includes('generateid') || content.includes('parameter'),
+    `Expected mention of prefix parameter, got: ${r2.body.message.content}`
+  );
+}, { slow: true });

package/test/integration/13-edge-cases.test.js

@@ -0,0 +1,99 @@
+'use strict';
+
+// ── Test 13: Edge cases and error handling ────────────────────────────────────
+
+await test('POST /agents/:name/chat with missing message body returns 400', async () => {
+  const res = await fetch('http://localhost:5050/agents/hello/chat', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({}),
+  });
+  assert.strictEqual(res.status, 400);
+  const body = await res.json();
+  assert.strictEqual(body.error.code, 'VALIDATION_ERROR');
+});
+
+await test('POST /agents/:name/chat with non-string message returns 400', async () => {
+  const res = await fetch('http://localhost:5050/agents/hello/chat', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: 42 }),
+  });
+  assert.strictEqual(res.status, 400);
+  const body = await res.json();
+  assert.strictEqual(body.error.code, 'VALIDATION_ERROR');
+});
+
+await test('POST /agents/analyst/task returns 400 for agent without chat mode', async () => {
+  // analyst only has task mode — no chat mode
+  const res = await client.chat.send('analyst', 'Hello');
+  assert.strictEqual(res.status, 400);
+  assert.strictEqual(res.body.error.code, 'MODE_NOT_SUPPORTED');
+});
+
+await test('POST /agents/hello/task with missing input returns 400', async () => {
+  const res = await fetch('http://localhost:5050/agents/hello/task', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({}),
+  });
+  assert.strictEqual(res.status, 400);
+  const body = await res.json();
+  assert.strictEqual(body.error.code, 'VALIDATION_ERROR');
+});
+
+await test('Task with very short input completes fine', async () => {
+  const res = await client.tasks.create('hello', 'Hi');
+  assert.strictEqual(res.status, 202);
+  const task = await client.pollTask(res.body.taskId, { timeout: 60000 });
+  assert.strictEqual(task.status, 'finished', `Task failed: ${task.error}`);
+  assert(task.output && task.output.length > 0, 'Should produce some output even for short input');
+}, { slow: true });
+
+await test('Task with very long input completes without crashing', async () => {
+  const longText = 'How many words are in this sentence: ' +
+    'The quick brown fox jumps over the lazy dog and the cat sat on the mat. '.repeat(5) +
+    ' Reply with just a number.';
+  const res = await client.tasks.create('hello', longText);
+  assert.strictEqual(res.status, 202);
+  const task = await client.pollTask(res.body.taskId, { timeout: 90000 });
+  // Task should complete (finished or failed) — not hang
+  assert(['finished', 'failed'].includes(task.status), `Expected terminal status, got: ${task.status}`);
+  if (task.status === 'finished') {
+    // Output may be a number or text — just verify something came back
+    assert(task.output !== undefined, 'output field should exist');
+  }
+}, { slow: true });
+
+await test('Session messages include correct roles', async () => {
+  const res = await client.chat.send('hello', 'Roles test message.');
+  const { sessionId } = res.body;
+  const msgsRes = await client.sessions.messages(sessionId);
+  assert.strictEqual(msgsRes.status, 200);
+  const roles = msgsRes.body.messages.map(m => m.role);
+  assert(roles.includes('system'), 'Missing system message');
+  assert(roles.includes('user'), 'Missing user message');
+  assert(roles.includes('assistant'), 'Missing assistant message');
+  const validRoles = new Set(['system', 'user', 'assistant', 'tool']);
+  roles.forEach(r => assert(validRoles.has(r), `Invalid role: ${r}`));
+});
+
+await test('Task events have valid types', async () => {
+  const res = await client.tasks.create('hello', 'Events validation test.');
+  const task = await client.pollTask(res.body.taskId, { timeout: 60000 });
+  const eventsRes = await client.tasks.events(task.id);
+  assert.strictEqual(eventsRes.status, 200);
+  const validTypes = new Set(['iteration.start', 'iteration.end', 'tool.start', 'tool.end',
+    'status.change', 'llm.error', 'limit.reached', 'custom', 'task.complete']);
+  for (const e of eventsRes.body.events) {
+    // Event types should be recognized patterns
+    const isKnown = [...validTypes].some(t => e.type.includes(t.split('.')[0]));
+    assert(isKnown || e.type, `Event type should be non-empty: ${e.type}`);
+  }
+}, { slow: true });
+
+await test('GET /tasks with limit parameter respected', async () => {
+  const res = await client.tasks.list({ limit: 2 });
+  assert.strictEqual(res.status, 200);
+  assert(res.body.tasks.length <= 2, `Limit 2 should return at most 2, got: ${res.body.tasks.length}`);
+});

package/test/integration/14-cancel.test.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// ── Test 14: Cancellation + token budget ─────────────────────────────────────
+
+await test('Cancel a pending task immediately', async () => {
+  const res = await client.tasks.create('hello', 'Count from 1 to 1000 slowly.');
+  assert.strictEqual(res.status, 202, JSON.stringify(res.body));
+  const { taskId } = res.body;
+
+  // Cancel right away (task should still be pending or just processing)
+  const cancelRes = await client.tasks.cancel(taskId);
+  assert.strictEqual(cancelRes.status, 200, JSON.stringify(cancelRes.body));
+  assert.strictEqual(cancelRes.body.taskId, taskId);
+
+  // Verify final state is canceled
+  await new Promise(r => setTimeout(r, 500));
+  const getRes = await client.tasks.get(taskId);
+  assert.strictEqual(getRes.status, 200);
+  assert(['canceled', 'finished', 'processing'].includes(getRes.body.task.status),
+    `Expected canceled/finished/processing, got: ${getRes.body.task.status}`);
+});
+
+await test('Canceling an already-finished task returns TASK_ALREADY_TERMINAL', async () => {
+  const res = await client.tasks.create('hello', 'Say: DONE_QUICK');
+  const task = await client.pollTask(res.body.taskId, { timeout: 60000 });
+  assert.strictEqual(task.status, 'finished');
+
+  const cancelRes = await client.tasks.cancel(task.id);
+  assert.strictEqual(cancelRes.status, 400, JSON.stringify(cancelRes.body));
+  assert.strictEqual(cancelRes.body.error.code, 'TASK_ALREADY_TERMINAL');
+}, { slow: true });
+
+await test('Task with tokenBudget field is accepted', async () => {
+  const res = await fetch('http://localhost:5050/agents/hello/task', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ input: 'Say: BUDGET_TEST', tokenBudget: 100000 }),
+  });
+  assert.strictEqual(res.status, 202, `Expected 202, got ${res.status}`);
+  const body = await res.json();
+  assert(body.taskId, 'taskId missing');
+});
+
+await test('Task failure produces structured error object', async () => {
+  // Create a task with an extremely small token budget that will definitely be exceeded
+  const res = await fetch('http://localhost:5050/agents/hello/task', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ input: 'Write a 5000 word essay on quantum physics.', tokenBudget: 1 }),
+  });
+  assert.strictEqual(res.status, 202);
+  const { taskId } = await res.json();
+
+  const task = await client.pollTask(taskId, { timeout: 30000 });
+  // Should fail with BUDGET_EXCEEDED or succeed if the LLM doesn't consume tokens
+  if (task.status === 'failed') {
+    assert(task.error, 'error field should be present on failed task');
+    const err = typeof task.error === 'object' ? task.error : JSON.parse(task.error);
+    assert(err.code, `error.code missing: ${JSON.stringify(task.error)}`);
+    assert(err.message, 'error.message missing');
+  }
+}, { slow: true });

package/test/integration/15-debug.test.js

@@ -0,0 +1,106 @@
+'use strict';
+
+// ── Test 15: Debuggability endpoints (context, events pagination) ─────────────
+
+const BASE = 'http://localhost:5050';
+
+await test('GET /tasks/:id/context returns null for pending task', async () => {
+  const res = await client.tasks.create('hello', 'Say: CONTEXT_TEST');
+  const { taskId } = res.body;
+
+  const ctxRes = await fetch(`${BASE}/tasks/${taskId}/context`);
+  assert.strictEqual(ctxRes.status, 200);
+  const body = await ctxRes.json();
+  assert.strictEqual(body.taskId, taskId);
+  // Context may be null if task hasn't started yet
+  assert('context' in body, 'context field should be present');
+});
+
+await test('GET /tasks/:id/context returns snapshot after task runs', async () => {
+  const res = await client.tasks.create('hello', 'Say: CONTEXT_SNAP');
+  const { taskId } = res.body;
+  await client.pollTask(taskId, { timeout: 60000 });
+
+  const ctxRes = await fetch(`${BASE}/tasks/${taskId}/context`);
+  assert.strictEqual(ctxRes.status, 200);
+  const body = await ctxRes.json();
+  assert.strictEqual(body.taskId, taskId);
+  if (body.context) {
+    assert(Array.isArray(body.context.messages), 'context.messages should be array');
+    assert(Array.isArray(body.context.tools), 'context.tools should be array');
+    assert(typeof body.context.iteration === 'number', 'context.iteration should be a number');
+    assert(body.context.messages.length > 0, 'should have at least one message');
+    // System prompt should be first
+    assert.strictEqual(body.context.messages[0].role, 'system');
+  }
+}, { slow: true });
+
+await test('GET /sessions/:id/context returns message list', async () => {
+  // Create a chat session
+  const chatRes = await fetch(`${BASE}/agents/hello/chat`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: 'Say: SESSION_CONTEXT_TEST' }),
+  });
+  assert.strictEqual(chatRes.status, 200);
+  const { sessionId } = await chatRes.json();
+
+  const ctxRes = await fetch(`${BASE}/sessions/${sessionId}/context`);
+  assert.strictEqual(ctxRes.status, 200);
+  const body = await ctxRes.json();
+  assert.strictEqual(body.sessionId, sessionId);
+  assert(typeof body.messageCount === 'number');
+  assert(Array.isArray(body.messages));
+  assert(body.messages.length >= 2, 'Should have system + user + assistant messages');
+  const roles = body.messages.map(m => m.role);
+  assert(roles.includes('system'), 'Should have system message');
+  assert(roles.includes('user'), 'Should have user message');
+}, { slow: true });
+
+await test('GET /tasks/:id/events?since= returns only newer events', async () => {
+  const res = await client.tasks.create('hello', 'Say: EVENTS_SINCE_TEST');
+  const { taskId } = res.body;
+  await client.pollTask(taskId, { timeout: 60000 });
+
+  // Get all events
+  const allRes = await client.tasks.events(taskId);
+  const allEvents = allRes.body.events;
+  assert(allEvents.length > 0, 'should have events');
+
+  // Get events since the first event id
+  const firstId = allEvents[0].id;
+  const sinceRes = await fetch(`${BASE}/tasks/${taskId}/events?since=${firstId}`);
+  assert.strictEqual(sinceRes.status, 200);
+  const sinceBody = await sinceRes.json();
+  assert(Array.isArray(sinceBody.events));
+  // All returned events should have id > firstId
+  sinceBody.events.forEach(e => {
+    assert(e.id > firstId, `Event id ${e.id} should be > ${firstId}`);
+  });
+  // Should have one fewer event than total
+  assert(sinceBody.events.length < allEvents.length, 'since should return fewer events');
+}, { slow: true });
+
+await test('GET /tasks/:id/events?limit= caps the result', async () => {
+  const res = await client.tasks.create('hello', 'Say: EVENTS_LIMIT_TEST');
+  const { taskId } = res.body;
+  await client.pollTask(taskId, { timeout: 60000 });
+
+  const limitRes = await fetch(`${BASE}/tasks/${taskId}/events?limit=1`);
+  assert.strictEqual(limitRes.status, 200);
+  const body = await limitRes.json();
+  assert(Array.isArray(body.events));
+  assert(body.events.length <= 1, `Expected at most 1 event, got ${body.events.length}`);
+}, { slow: true });
+
+await test('Task response includes eventCount field', async () => {
+  const res = await client.tasks.create('hello', 'Say: EVENTCOUNT_TEST');
+  const { taskId } = res.body;
+  await client.pollTask(taskId, { timeout: 60000 });
+
+  const getRes = await client.tasks.get(taskId);
+  assert.strictEqual(getRes.status, 200);
+  const task = getRes.body.task;
+  assert(typeof task.eventCount === 'number', `eventCount should be a number, got: ${typeof task.eventCount}`);
+  assert(task.eventCount > 0, `eventCount should be > 0, got: ${task.eventCount}`);
+}, { slow: true });

package/test/integration/16-memory-api.test.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// ── Test 16: Memory API ───────────────────────────────────────────────────────
+
+const BASE = 'http://localhost:5050';
+
+await test('GET /agents/:name/memory lists memory files', async () => {
+  const res = await fetch(`${BASE}/agents/hello/memory`);
+  assert.strictEqual(res.status, 200);
+  const body = await res.json();
+  assert.strictEqual(body.agentName, 'hello');
+  assert(Array.isArray(body.files), 'files should be array');
+});
+
+await test('PUT /agents/:name/memory/:file writes a memory file', async () => {
+  const content = '## Test Memory\n\nThis was written by the test suite.';
+  const res = await fetch(`${BASE}/agents/hello/memory/TEST-MEMORY.md`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ content }),
+  });
+  assert.strictEqual(res.status, 200, JSON.stringify(await res.clone().json().catch(() => ({}))));
+  const body = await res.json();
+  assert.strictEqual(body.agentName, 'hello');
+  assert.strictEqual(body.file, 'TEST-MEMORY.md');
+  assert(typeof body.size === 'number');
+});
+
+await test('GET /agents/:name/memory/:file reads back written content', async () => {
+  const content = '## Read Test\n\nRead me back correctly.';
+  await fetch(`${BASE}/agents/hello/memory/READ-TEST.md`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ content }),
+  });
+
+  const res = await fetch(`${BASE}/agents/hello/memory/READ-TEST.md`);
+  assert.strictEqual(res.status, 200);
+  const body = await res.json();
+  assert.strictEqual(body.content, content);
+  assert.strictEqual(body.file, 'READ-TEST.md');
+});
+
+await test('GET /agents/:name/memory/:file returns 404 for missing file', async () => {
+  const res = await fetch(`${BASE}/agents/hello/memory/DOES-NOT-EXIST.md`);
+  assert.strictEqual(res.status, 404);
+  const body = await res.json();
+  assert.strictEqual(body.error.code, 'NOT_FOUND');
+});
+
+await test('PUT /agents/:name/memory/:file rejects path traversal filenames', async () => {
+  const res = await fetch(`${BASE}/agents/hello/memory/../../evil.md`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ content: 'malicious' }),
+  });
+  // Should be blocked by routing or validation
+  assert([400, 404].includes(res.status), `Expected 400 or 404, got ${res.status}`);
+});
+
+await test('DELETE /agents/:name/memory/:file removes the file', async () => {
+  // First write
+  await fetch(`${BASE}/agents/hello/memory/DELETE-TEST.md`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ content: 'to be deleted' }),
+  });
+
+  // Then delete
+  const res = await fetch(`${BASE}/agents/hello/memory/DELETE-TEST.md`, { method: 'DELETE' });
+  assert.strictEqual(res.status, 200);
+  const body = await res.json();
+  assert.strictEqual(body.status, 'deleted');
+
+  // Verify gone
+  const getRes = await fetch(`${BASE}/agents/hello/memory/DELETE-TEST.md`);
+  assert.strictEqual(getRes.status, 404);
+});
+
+await test('Cleanup: remove test memory files', async () => {
+  await fetch(`${BASE}/agents/hello/memory/TEST-MEMORY.md`, { method: 'DELETE' });
+  await fetch(`${BASE}/agents/hello/memory/READ-TEST.md`, { method: 'DELETE' });
+});

package/test/integration/17-settings-api.test.js

@@ -0,0 +1,41 @@
+'use strict';
+
+// ── Test 17: Settings API ─────────────────────────────────────────────────────
+
+const BASE = 'http://localhost:5050';
+
+await test('GET /settings returns current settings with redacted api_key', async () => {
+  const res = await fetch(`${BASE}/settings`);
+  assert.strictEqual(res.status, 200);
+  const body = await res.json();
+  assert(body.settings, 'settings object missing');
+  assert(typeof body.settings.port === 'number', 'port should be a number');
+  // api_key should be redacted if present
+  if (body.settings.models?.main?.api_key) {
+    const key = body.settings.models.main.api_key;
+    assert(!key.startsWith('sk-or-v1-') || key.includes('…'), 'api_key should be redacted');
+  }
+});
+
+await test('PUT /settings with invalid body returns 400 VALIDATION_ERROR', async () => {
+  const res = await fetch(`${BASE}/settings`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ port: 'not-a-number' }),
+  });
+  // May be 400 if schema validation catches it, or 200 if schema is relaxed
+  // At minimum we should get a JSON response
+  const body = await res.json();
+  assert(body, 'should return JSON');
+});
+
+await test('GET /settings returns valid JSON structure', async () => {
+  const res = await fetch(`${BASE}/settings`);
+  assert.strictEqual(res.status, 200);
+  const body = await res.json();
+  const s = body.settings;
+  assert(s.permissions, 'permissions missing');
+  assert(Array.isArray(s.permissions.allow), 'permissions.allow should be array');
+  assert(s.compaction, 'compaction missing');
+  assert(s.memory, 'memory missing');
+});