nanocoai/nanoclaw / .claude/skills/add-codex
add-codex
FlaggedUse Codex (OpenAI's codex app-server) as a full agent provider — planning, tool orchestration, MCP tools, server-side history, session resume — alongside or instead of Claude. ChatGPT subscription or OpenAI API key, vault-only via the selected gateway. Per-group via `ncl groups config update --provider codex`. Distinct from using OpenAI as an MCP tool (where Claude remains the planner).
payload/src/providers/codex-agents-md.test.ts
View on GitHub/**
* The Codex project-doc cap must DEGRADE, never throw: composeGroupAgentsMd
* runs inside the provider contribution at every spawn, and a throw there rides
* wakeContainer's transient-retry contract — host-sweep respawns every 60s
* forever and the group goes silently dark (a permanent condition disguised as
* a transient one). Oversized docs drop their largest optional instruction
* sections, keep the core contract, and say so in the doc.
*/
import fs from 'fs';
import os from 'os';
import path from 'path';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
vi.mock('../config.js', async (importOriginal) => ({
...(await importOriginal<typeof import('../config.js')>()),
DATA_DIR: '/tmp/nanoclaw-agents-md-test/data',
}));
import { composeGroupAgentsMd, CODEX_PROJECT_DOC_MAX_BYTES } from './codex-agents-md.js';
import { closeDb, createAgentGroup, initTestDb, runMigrations } from '../db/index.js';
import { ensureContainerConfig, updateContainerConfigJson } from '../db/container-configs.js';
import type { AgentGroup } from '../types.js';
const TEST_ROOT = '/tmp/nanoclaw-agents-md-test';
// This module is the pre-contract compatibility path: on a contract core the
// canonical template composes AGENTS.md and this spec is never consulted, so
// its cap-handling guards only apply where the legacy path is live.
const legacyIt = fs.existsSync(path.join(process.cwd(), 'src/provider-contracts/realize.ts')) ? it.skip : it;
function group(folder: string): AgentGroup {
return {
id: `ag-${folder}`,
name: folder,
folder,
agent_provider: null,
created_at: new Date().toISOString(),
} as AgentGroup;
}
describe('composeGroupAgentsMd cap handling', () => {
beforeEach(async () => {
if (fs.existsSync(TEST_ROOT)) fs.rmSync(TEST_ROOT, { recursive: true });
fs.mkdirSync(path.join(TEST_ROOT, 'data'), { recursive: true });
const db = await initTestDb();
await runMigrations(db);
});
afterEach(async () => {
await closeDb();
if (fs.existsSync(TEST_ROOT)) fs.rmSync(TEST_ROOT, { recursive: true });
});
legacyIt('writes the doc untouched when under the cap', async () => {
const g = group('small');
await createAgentGroup(g);
await ensureContainerConfig(g.id);
const groupDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-md-'));
try {
await composeGroupAgentsMd(g, groupDir);
const doc = fs.readFileSync(path.join(groupDir, 'AGENTS.md'), 'utf-8');
expect(doc).not.toContain('Omitted for size');
// Agent-authored skills must be told a home that is BOTH persistent and
// codex-discovered (~/.codex/skills). /workspace/agent/skills is not
// scanned by codex, so authored skills there never trigger.
expect(doc).toContain('~/.codex/skills');
expect(doc).toContain('linked memory files');
expect(doc).not.toContain('memories, data');
expect(Buffer.byteLength(doc, 'utf-8')).toBeLessThanOrEqual(CODEX_PROJECT_DOC_MAX_BYTES);
} finally {
fs.rmSync(groupDir, { recursive: true, force: true });
}
});
legacyIt('never reads or inlines the host memory index', async () => {
const g = group('with-memory');
await createAgentGroup(g);
await ensureContainerConfig(g.id);
const groupDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-md-'));
try {
const sentinel = path.join(TEST_ROOT, 'host-secret');
fs.writeFileSync(sentinel, 'must not enter AGENTS.md\n');
fs.mkdirSync(path.join(groupDir, 'memory'), { recursive: true });
fs.symlinkSync(sentinel, path.join(groupDir, 'memory', 'index.md'));
await composeGroupAgentsMd(g, groupDir);
const doc = fs.readFileSync(path.join(groupDir, 'AGENTS.md'), 'utf-8');
expect(doc).toContain('supplied by NanoClaw at session startup');
expect(doc).not.toContain('must not enter AGENTS.md');
} finally {
fs.rmSync(groupDir, { recursive: true, force: true });
}
});
legacyIt('degrades instead of throwing when MCP instructions push the doc over the cap', async () => {
const g = group('oversized');
await createAgentGroup(g);
await ensureContainerConfig(g.id);
await updateContainerConfigJson(g.id, 'mcp_servers', {
bloated: { command: 'x', instructions: 'y'.repeat(CODEX_PROJECT_DOC_MAX_BYTES + 1024) },
lean: { command: 'x', instructions: 'short and useful' },
});
const groupDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-md-'));
try {
await composeGroupAgentsMd(g, groupDir); // must not throw
const doc = fs.readFileSync(path.join(groupDir, 'AGENTS.md'), 'utf-8');
expect(Buffer.byteLength(doc, 'utf-8')).toBeLessThanOrEqual(CODEX_PROJECT_DOC_MAX_BYTES);
// Largest optional section dropped, named in the doc; the rest survive.
expect(doc).toContain('Omitted for size');
expect(doc).toContain('MCP Server: bloated');
expect(doc).toContain('short and useful');
expect(doc).toContain('Memory System');
} finally {
fs.rmSync(groupDir, { recursive: true, force: true });
}
});
});
// The container writes the cap into Codex's config.toml. If the two numbers
// differ, Codex truncates a doc the host thought fit, or the host drops
// sections Codex would have loaded. Runs on every core, not only legacy ones.
describe('Codex project-doc cap', () => {
it('matches the cap the container writes into config.toml', () => {
const source = fs.readFileSync(
new URL('../../container/agent-runner/src/providers/codex-app-server.ts', import.meta.url),
'utf-8',
);
const match = source.match(/^const CODEX_PROJECT_DOC_MAX_BYTES = ([\d_]+(?:\s*\*\s*[\d_]+)*);$/m);
expect(match, 'CODEX_PROJECT_DOC_MAX_BYTES not found in codex-app-server.ts').not.toBeNull();
const containerCap = match![1]
.split('*')
.reduce((product, factor) => product * Number(factor.replace(/_/g, '').trim()), 1);
expect(containerCap).toBe(CODEX_PROJECT_DOC_MAX_BYTES);
});
});
// The persona rules (leads the document, never evicted, absent without a
// prepend file) belong to the shared composer and are pinned in trunk's
// src/project-doc-compose.test.ts. Re-asserting them here would pin trunk
// behavior from a branch that cannot be edited in the same change.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |