Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
# Load explicitly with Node --env-file=.env; the runtime does not auto-load cwd .env.
# Inherited environment values override this file.
# Blank optional key/base URL/host/auth/budget values mean absent, not zero.
# Provider selection stays explicit; openai still needs a key and production needs auth.
NODE_ENV=development
NOORG_LLM_PROVIDER=local
OPENAI_API_KEY=
Expand Down
13 changes: 11 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,19 @@ NoOrg is an active research runtime at working-copy maturity. The default develo
npm install
cp .env.example .env
npm run validate
npm start
node --env-file=.env --import tsx src/index.ts
```

The default development profile uses the deterministic local provider and requires no network access. Production requires `NOORG_LLM_PROVIDER=openai` and `OPENAI_API_KEY`.
Configuration reads `process.env`: a cwd `.env` is not loaded automatically by
`npm start` or `npm run start:dev`. Node's explicit `--env-file` loads it, and
inherited environment values take precedence. After a separately verified build,
the corresponding launch is `node --env-file=.env dist/index.js`.

Keep `NOORG_LLM_PROVIDER` explicit. The local development profile needs no model
credentials; `OPENAI_API_KEY` is required only for `openai`. Production also
requires `NOORG_HTTP_AUTH_TOKEN`. Blank optional key/base URL/host/auth/budget
values mean absent, not an implicit provider or permission to omit production
authentication. Nonempty invalid values still fail validation.

## Runtime surface

Expand Down
30 changes: 30 additions & 0 deletions src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,36 @@ TypeScript source for the NoOrg runtime. `src/index.ts` is the composition root;
- All dependencies are constructor-injected and every background resource exposes a shutdown path.
- Errors are structured and actionable; secrets are never logged.

## Runtime contracts

Public task pages remain capped at 100. Scheduling, health and metrics use
complete internal snapshots. `blockedTasks` counts the union of capability,
capacity, relationship and backoff blockers without double-counting; the
capability/capacity classifications are not a complete partition of that total.

State mutations publish committed values, revisions and task maps only after
durable replacement. Rejected pre-rename write/fsync candidates stay invisible
and cannot become a later flush or shutdown state. Rename/directory-sync
uncertainty may leave new raw disk bytes without acknowledgement: it fences
the store and retains its namespace guard. Guards are never automatically
reclaimed. Stop writers, preserve state/owner/guard/temp physical evidence and
obtain explicit reviewed recovery; never reset or roll back blindly.

Provider task counters are cumulative per provider instance; the coordinator
durably commits only new deltas and advances checkpoints only after success.
Fresh provider counters do not subtract persisted historical usage. Late
cancellation/timeout settlement records usage once without publishing a result.
Disabled rate limiting retains no request-time history; enabled windows retain
their existing quota, rollover, circuit and budget semantics.

Execution timers are cleared when the agent/timeout race settles, before durable
completion, accounting or event delivery. Reservation ownership lasts through
finalization; genuine timed-out work retains its reservation until the actual
operation settles. Structured task failures retain their original code in the
health observation rather than being reclassified as an unknown error.
Shutdown settles an already pending claim without claiming or cancelling the
remaining queued backlog, which stays persisted for the next process.

## Commands

```bash
Expand Down
20 changes: 12 additions & 8 deletions src/config/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,13 @@ function integer(name: string, fallback: number, minimum: number, maximum?: numb
);
}

function blankOptional<T extends z.ZodType>(schema: T) {
return z.preprocess(
value => (typeof value === 'string' && value.trim() === '' ? undefined : value),
schema.optional()
);
}

export interface AppConfig {
readonly environment: 'development' | 'test' | 'production';
readonly provider: ProviderKind;
Expand Down Expand Up @@ -59,17 +66,17 @@ export interface AppConfig {
const rawSchema = z.object({
NODE_ENV: environmentSchema.default('development'),
NOORG_LLM_PROVIDER: providerSchema,
OPENAI_API_KEY: z.string().trim().min(1).optional(),
OPENAI_API_KEY: blankOptional(z.string().trim().min(1)),
OPENAI_MODEL: z.string().trim().min(1).default('gpt-4o-mini'),
OPENAI_BASE_URL: z.string().url().optional(),
OPENAI_BASE_URL: blankOptional(z.string().url()),
OPENAI_TIMEOUT_MS: integer('OPENAI_TIMEOUT_MS', 30000, 1000),
OPENAI_MAX_RETRIES: integer('OPENAI_MAX_RETRIES', 2, 0),
OPENAI_RETRY_BASE_MS: integer('OPENAI_RETRY_BASE_MS', 250, 50),
OPENAI_PROMPT_COST_PER_MILLION_USD: z.coerce.number().finite().min(0).default(0),
OPENAI_COMPLETION_COST_PER_MILLION_USD: z.coerce.number().finite().min(0).default(0),
NOORG_HOST: z.string().trim().min(1).optional(),
NOORG_HOST: blankOptional(z.string().trim().min(1)),
NOORG_PORT: integer('NOORG_PORT', 3000, 1),
NOORG_HTTP_AUTH_TOKEN: z.string().trim().min(1).optional(),
NOORG_HTTP_AUTH_TOKEN: blankOptional(z.string().trim().min(1)),
NOORG_HTTP_MAX_BODY_BYTES: integer('NOORG_HTTP_MAX_BODY_BYTES', 1_048_576, 1024),
NOORG_STATE_PATH: z.string().trim().min(1).default('data/state.json'),
NOORG_POLL_INTERVAL_MS: integer('NOORG_POLL_INTERVAL_MS', 100, 10),
Expand All @@ -80,10 +87,7 @@ const rawSchema = z.object({
NOORG_MAX_RESULT_BYTES: integer('NOORG_MAX_RESULT_BYTES', 1_048_576, 1024),
NOORG_MAX_WORKFLOW_DEPTH: integer('NOORG_MAX_WORKFLOW_DEPTH', 32, 1, 64),
NOORG_MAX_WORKFLOW_CHILDREN: integer('NOORG_MAX_WORKFLOW_CHILDREN', 100, 1),
NOORG_PROVIDER_BUDGET_USD: z.preprocess(
value => (value === undefined || value === '' ? undefined : value),
z.coerce.number().finite().min(0).optional()
),
NOORG_PROVIDER_BUDGET_USD: blankOptional(z.coerce.number().finite().min(0)),
NOORG_PROVIDER_MAX_REQUESTS_PER_MINUTE: integer('NOORG_PROVIDER_MAX_REQUESTS_PER_MINUTE', 0, 0),
NOORG_PROVIDER_CIRCUIT_FAILURE_THRESHOLD: integer(
'NOORG_PROVIDER_CIRCUIT_FAILURE_THRESHOLD',
Expand Down
134 changes: 109 additions & 25 deletions src/coordination/coordinator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import type {
TaskRequest,
TaskStatus,
} from '../domain/types';
import { usageMetadataSchema, type UsageMetadata } from '../domain/types';
import type { Agent } from '../agents/abstract-agent';
import type { AgentAvailability, AgentRegistry } from '../agents/registry';
import type { Logger } from '../logging/logger';
Expand Down Expand Up @@ -70,6 +71,8 @@ export class Coordinator implements TaskScheduler {
private shutdownTimedOut = false;
private startPromise: Promise<void> | undefined;
private shutdownPromise: Promise<void> | undefined;
private readonly usageCheckpoints = new Map<string, UsageMetadata>();
private readonly usageMutations = new Map<string, Promise<void>>();

public constructor(private readonly dependencies: CoordinatorDependencies) {
this.repository =
Expand Down Expand Up @@ -163,16 +166,16 @@ export class Coordinator implements TaskScheduler {
readonly registryReady: boolean;
readonly shutdownTimedOut: boolean;
readonly lastFailure?: FailureObservation;
readonly usage: ReturnType<LLMProvider['getUsage']>;
readonly usage: UsageMetadata;
} {
const queued = this.repository.list('queued');
const { tasks: queued, total: queueDepth } = this.repository.internalSnapshot('queued');
const blocked = this.blockedTaskCounts(queued);
const health = {
status: this.status,
provider: this.dependencies.provider.kind,
agents: this.dependencies.registry.descriptors().length,
activeTasks: this.dependencies.registry.activeCount(),
queueDepth: queued.length,
queueDepth,
blockedTasks: blocked.total,
blockedCapabilityTasks: blocked.capability,
blockedCapacityTasks: blocked.capacity,
Expand All @@ -184,7 +187,7 @@ export class Coordinator implements TaskScheduler {
...(this.lastFailure === undefined ? {} : { lastFailure: this.lastFailure }),
usage: this.dependencies.provider.getUsage(),
};
this.refreshMetrics(health.usage);
this.refreshMetrics(health.usage, queued, blocked);
return health;
}

Expand All @@ -208,6 +211,11 @@ export class Coordinator implements TaskScheduler {
try {
await this.dependencies.state.load();
await this.repository.load();
for (const task of this.repository.internalSnapshot().tasks) {
const currentUsage = this.dependencies.provider.getTaskUsage?.(task.id);
if (currentUsage !== undefined)
this.usageCheckpoints.set(task.id, usageMetadataSchema.parse(currentUsage));
}
const recovered = await this.repository.recoverInterruptedTasks();
await this.dependencies.registry.initialize({
provider: this.dependencies.provider,
Expand Down Expand Up @@ -307,9 +315,8 @@ export class Coordinator implements TaskScheduler {
0,
this.dependencies.maxConcurrentTasks - this.dependencies.registry.activeCount()
);
if (available === 0) return 0;
for (const task of this.repository.list('queued')) {
if (launched >= available) break;
for (const task of this.repository.internalSnapshot('queued').tasks) {
if (this.status !== 'running') break;
const now = this.dependencies.clock.now().getTime();
if (task.deadlineAt !== undefined && Date.parse(task.deadlineAt) <= now) {
const expired = await this.repository.failQueued(task.id, {
Expand Down Expand Up @@ -346,6 +353,7 @@ export class Coordinator implements TaskScheduler {
continue;
}
if (parentState === 'blocked') continue;
if (launched >= available) continue;
const candidate = this.toAgentTask(task);
const lease = this.dependencies.registry.acquire(candidate);
if (!lease) continue;
Expand All @@ -361,6 +369,19 @@ export class Coordinator implements TaskScheduler {
});
continue;
}
if (this.status !== 'running') {
try {
if (this.repository.get(started.id)?.status === 'running')
await this.cancelTask(started.id);
} finally {
lease.release();
}
break;
}
if (this.repository.get(started.id)?.status !== 'running') {
lease.release();
continue;
}
const controller = new AbortController();
this.taskControllers.set(started.id, controller);
const execution = this.execute(started, lease.agent, controller, lease.release);
Expand Down Expand Up @@ -405,21 +426,25 @@ export class Coordinator implements TaskScheduler {
});

try {
const result = await Promise.race([operation, timeout]);
let result: AgentResult;
try {
result = await Promise.race([operation, timeout]);
} finally {
clearTimeout(timer);
}
const current = this.repository.get(task.id);
if (this.status === 'running' && current?.status === 'running') {
const taskUsage = this.dependencies.provider.getTaskUsage?.(task.id);
const completed = await this.repository.completeWithUsage(
task.id,
agent.validateResult(result),
taskUsage
const completed = await this.commitProviderUsage(task.id, usage =>
this.repository.completeWithUsage(task.id, agent.validateResult(result), usage)
);
this.dependencies.metrics.increment('tasks_completed');
this.dependencies.metrics.observe(
'task_duration_ms',
this.dependencies.clock.now().getTime() - startedAt
);
await this.publishSafely('task.completed', completed);
} else {
await this.recordProviderUsage(task.id);
}
} catch (error) {
if (timedOut) {
Expand All @@ -442,7 +467,6 @@ export class Coordinator implements TaskScheduler {
}
}
} finally {
if (timer) clearTimeout(timer);
release();
this.taskControllers.delete(task.id);
}
Expand All @@ -455,7 +479,7 @@ export class Coordinator implements TaskScheduler {
this.dependencies.metrics.increment(
failed.status === 'queued' ? 'tasks_retried' : 'tasks_failed'
);
this.recordFailure(error);
this.recordTaskFailure(error);
await this.publishSafely(failed.status === 'queued' ? 'task.requeued' : 'task.failed', failed);
}

Expand Down Expand Up @@ -541,12 +565,58 @@ export class Coordinator implements TaskScheduler {
}

private async recordProviderUsage(taskId: string): Promise<void> {
const usage = this.dependencies.provider.getTaskUsage?.(taskId);
if (usage === undefined || (usage.totalTokens === 0 && usage.costUsd === 0)) return;
await this.repository.recordUsage(taskId, usage).catch(error => {
if (!(error instanceof NoOrgError && error.code === 'INVALID_TASK_TRANSITION'))
this.recordFailure(error);
await this.commitProviderUsage(taskId, async usage => {
if (usage !== undefined) await this.repository.recordUsage(taskId, usage);
}).catch(error => this.recordFailure(error));
}

private commitProviderUsage<T>(
taskId: string,
commit: (delta: UsageMetadata | undefined) => Promise<T>
): Promise<T> {
const previous = this.usageMutations.get(taskId) ?? Promise.resolve();
const operation = previous.then(async () => {
const observed = this.dependencies.provider.getTaskUsage?.(taskId);
const current = observed === undefined ? undefined : usageMetadataSchema.parse(observed);
const checkpoint = this.usageCheckpoints.get(taskId) ?? {
promptTokens: 0,
completionTokens: 0,
totalTokens: 0,
costUsd: 0,
};
let delta: UsageMetadata | undefined;
if (current !== undefined) {
if (
current.promptTokens < checkpoint.promptTokens ||
current.completionTokens < checkpoint.completionTokens ||
current.totalTokens < checkpoint.totalTokens ||
current.costUsd < checkpoint.costUsd
)
throw new NoOrgError(
'PROVIDER_USAGE_REGRESSED',
'Provider-instance usage counters decreased'
);
const added = {
promptTokens: current.promptTokens - checkpoint.promptTokens,
completionTokens: current.completionTokens - checkpoint.completionTokens,
totalTokens: current.totalTokens - checkpoint.totalTokens,
costUsd: current.costUsd - checkpoint.costUsd,
};
if (Object.values(added).some(value => value !== 0)) delta = added;
}
const result = await commit(delta);
if (current !== undefined) this.usageCheckpoints.set(taskId, current);
return result;
});
const settled = operation.then(
() => undefined,
() => undefined
);
this.usageMutations.set(taskId, settled);
void settled.then(() => {
if (this.usageMutations.get(taskId) === settled) this.usageMutations.delete(taskId);
});
return operation;
}

private async publishSafely(type: string, task: TaskRecord): Promise<void> {
Expand All @@ -566,17 +636,22 @@ export class Coordinator implements TaskScheduler {
}

private recordFailure(error: unknown): void {
const taskError = toTaskError(error);
this.recordTaskFailure(toTaskError(error));
}

private recordTaskFailure(taskError: TaskError): void {
this.lastFailure = {
code: taskError.code,
message: taskError.message,
timestamp: this.dependencies.clock.now().toISOString(),
};
}

private refreshMetrics(usage: ReturnType<LLMProvider['getUsage']>): void {
const queued = this.repository.list('queued');
const blocked = this.blockedTaskCounts(queued);
private refreshMetrics(
usage: UsageMetadata,
queued: readonly TaskRecord[] = this.repository.internalSnapshot('queued').tasks,
blocked = this.blockedTaskCounts(queued)
): void {
this.dependencies.metrics.setGauge('active_tasks', this.dependencies.registry.activeCount());
this.dependencies.metrics.setGauge('queue_depth', queued.length);
this.dependencies.metrics.setGauge('blocked_tasks', blocked.total);
Expand All @@ -593,13 +668,22 @@ export class Coordinator implements TaskScheduler {
readonly capability: number;
readonly capacity: number;
} {
let total = 0;
const now = this.dependencies.clock.now().getTime();
let capability = 0;
let capacity = 0;
for (const task of tasks) {
const availability = this.agentAvailability(task);
if (availability === 'no_match') capability += 1;
if (availability === 'at_capacity') capacity += 1;
if (
availability !== 'available' ||
this.dependencyState(task) !== 'ready' ||
this.parentState(task) !== 'ready' ||
(task.nextAttemptAt !== undefined && Date.parse(task.nextAttemptAt) > now)
)
total += 1;
}
return { total: capability + capacity, capability, capacity };
return { total, capability, capacity };
}
}
2 changes: 2 additions & 0 deletions src/domain/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,8 @@ export const taskQuerySchema = z
})
.strict();

export type ParsedTaskQuery = z.infer<typeof taskQuerySchema>;

export interface TaskRecord {
readonly id: string;
readonly name: string;
Expand Down
Loading
Loading