@amoree-code/ocean 0.0.0-stage → 1.1.0

package/node_modules/@ocean/core/dist/domain/sessions/handoff.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+const handoffSchema = z.object({
+    handoffId: z.string().min(1),
+    taskId: z.string().nullable(),
+    title: z.string().min(1),
+    objective: z.string().default(""),
+    state: z.string().min(1),
+    profileId: z.string().default(""),
+    profileIdentity: z.string().default(""),
+    sourceSessionId: z.string().nullable(),
+    projectId: z.string().nullable().default(null),
+    provider: z.string().default(""),
+    parentSessionId: z.string().nullable(),
+    decisions: z.array(z.string()).default([]),
+    changedFiles: z.array(z.string()).default([]),
+    commit: z.string().nullable(),
+    verification: z.array(z.string()).default([]),
+    notProven: z.array(z.string()).default([]),
+    blocked: z.array(z.string()).default([]),
+    permissions: z.record(z.string(), z.unknown()).default({}),
+    contextManifest: z.record(z.string(), z.unknown()).default({}),
+    nextAction: z.string().default(""),
+    sourceSummaryPath: z.string().nullable().default(null),
+    content: z.string().max(16_000).default(""),
+    contentBytes: z.number().int().nonnegative().default(0),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+});
+export function validateHandoff(input) {
+    return handoffSchema.parse(input);
+}
+export function compactHandoff(handoff, maxBytes = 8_000) {
+    const value = {
+        handoffId: handoff.handoffId,
+        taskId: handoff.taskId,
+        title: handoff.title,
+        objective: handoff.objective,
+        state: handoff.state,
+        profileId: handoff.profileId,
+        provider: handoff.provider,
+        commit: handoff.commit,
+        decisions: handoff.decisions,
+        changedFiles: handoff.changedFiles,
+        verification: handoff.verification,
+        notProven: handoff.notProven,
+        blocked: handoff.blocked,
+        permissions: handoff.permissions,
+        contextManifest: handoff.contextManifest,
+        nextAction: handoff.nextAction,
+        sourceSummaryPath: handoff.sourceSummaryPath,
+    };
+    const serialize = (candidate) => JSON.stringify(candidate);
+    let serialized = serialize(value);
+    if (Buffer.byteLength(serialized) <= maxBytes)
+        return serialized;
+    const compact = {
+        ...value,
+        decisions: value.decisions.slice(0, 8),
+        changedFiles: value.changedFiles.slice(0, 24),
+        verification: value.verification.slice(0, 8),
+        notProven: value.notProven.slice(0, 8),
+        blocked: value.blocked.slice(0, 8),
+        permissions: {},
+        contextManifest: {},
+    };
+    serialized = serialize(compact);
+    if (Buffer.byteLength(serialized) <= maxBytes)
+        return serialized;
+    return JSON.stringify({
+        handoffId: handoff.handoffId,
+        taskId: handoff.taskId,
+        title: handoff.title,
+        state: handoff.state,
+        nextAction: handoff.nextAction,
+        truncated: true,
+    });
+}
+//# sourceMappingURL=handoff.js.map

package/node_modules/@ocean/core/dist/domain/sessions/session.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+const sessionStatusSchema = z.enum([
+    "created",
+    "running",
+    "completed",
+    "failed",
+    "cancelled",
+]);
+export const sessionSchema = z.object({
+    sessionId: z.string().min(1),
+    title: z.string().default(""),
+    taskId: z.string().nullable().default(null),
+    handoffId: z.string().nullable().default(null),
+    provider: z.string().min(1),
+    providerSessionId: z.string().nullable(),
+    parentSessionId: z.string().nullable(),
+    profile: z.string().min(1),
+    profileIdentity: z.string().default(""),
+    workingDirectory: z.string().min(1),
+    status: sessionStatusSchema,
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+    resumeData: z.string().nullable(),
+    contextHash: z.string().nullable().default(null),
+    contextBytes: z.number().int().nonnegative().default(0),
+    nextAction: z.string().default(""),
+    verificationStatus: z
+        .enum(["unknown", "proven", "not_proven", "blocked"])
+        .default("unknown"),
+    summaryPath: z.string().nullable().default(null),
+    summaryHash: z.string().nullable().default(null),
+    summaryBytes: z.number().int().nonnegative().default(0),
+    closeoutStatus: z.enum(["pending", "completed", "failed"]).default("pending"),
+    closeoutVersion: z.string().default("1"),
+    closedAt: z.string().nullable().default(null),
+    projectId: z.string().nullable().default(null),
+});
+// created: a session has been persisted but has not been sent to a provider yet.
+// running: a headless provider run is in progress for this session.
+// completed / failed: the most recent run finished; the session can still be resumed
+//   (running is reachable again) because "completed"/"failed" describe the last run,
+//   not the session's availability.
+// cancelled: terminal. A cancelled session is never resumed.
+const allowedTransitions = {
+    created: ["running"],
+    running: ["completed", "failed", "cancelled"],
+    completed: ["running"],
+    failed: ["running"],
+    cancelled: [],
+};
+export function assertValidStatusTransition(from, to) {
+    if (from === to)
+        return;
+    if (!allowedTransitions[from].includes(to)) {
+        throw new Error(`Invalid session status transition: ${from} -> ${to}`);
+    }
+}
+//# sourceMappingURL=session.js.map

package/node_modules/@ocean/core/dist/domain/skills/default-skills.js

@@ -0,0 +1,29 @@
+const DEFAULT_SKILLS = [
+    "design-thinking",
+    "business-logic",
+    "core-thinking",
+    "verification",
+    "loop",
+];
+export function defaultSkillNames(_role) {
+    const role = _role.toLowerCase();
+    if (role.includes("research"))
+        return [
+            "design-thinking",
+            "business-logic",
+            "core-thinking",
+            "verification",
+        ];
+    if (role.includes("test"))
+        return [
+            "design-thinking",
+            "business-logic",
+            "verification",
+            "use-browser",
+            "loop",
+        ];
+    if (role.includes("developer") || role.includes("engineer"))
+        return [...DEFAULT_SKILLS, "use-browser"];
+    return [...DEFAULT_SKILLS, "use-browser"];
+}
+//# sourceMappingURL=default-skills.js.map

package/node_modules/@ocean/core/dist/domain/skills/skill-validator.js

@@ -0,0 +1,5 @@
+import { skillSchema } from "./skill.js";
+export function validateSkill(input) {
+    return skillSchema.parse(input);
+}
+//# sourceMappingURL=skill-validator.js.map

package/node_modules/@ocean/core/dist/domain/skills/skill.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export const skillMetadataSchema = z.object({
+    name: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    description: z.string().min(1),
+    version: z.string().min(1),
+    category: z.enum(["core", "role", "project", "personal"]),
+});
+export const skillSchema = skillMetadataSchema.extend({
+    instructions: z.string().min(1),
+});
+//# sourceMappingURL=skill.js.map

package/node_modules/@ocean/core/dist/domain/tasks/task-id.js

@@ -0,0 +1,85 @@
+// Task identifiers: <PREFIX>-<number> (T-256). Pure — no I/O. Every place that used to hard-code
+// `T-\d+` goes through here, so the legacy `T` namespace and per-project prefixes (OL-001) are
+// one rule.
+// The namespace every task had before prefixes existed; it stays valid forever.
+export const LEGACY_PREFIX = "T";
+export const PREFIX_SHAPE = /^[A-Z][A-Z0-9]{0,5}$/;
+export const TASK_ID = /^[A-Z][A-Z0-9]{0,5}-\d{1,6}$/;
+// Real-world tokens shaped like an id ("UTF-8", "SHA-256", "ISO-8601", "GPT-5"): a project
+// may never claim one, or free text would turn every mention into a task reference.
+export const RESERVED_PREFIXES = [
+    "CVE",
+    "GPT",
+    "HTTP",
+    "ISO",
+    "PR",
+    "RFC",
+    "SHA",
+    "TLS",
+    "UTF",
+];
+export function isValidPrefix(value) {
+    return PREFIX_SHAPE.test(value) && !RESERVED_PREFIXES.includes(value);
+}
+// Case-insensitive on input (`t-45`, `ol-1`), canonical upper-case prefix on output.
+export function parseTaskId(value) {
+    const match = /^([A-Za-z][A-Za-z0-9]{0,5})-(\d{1,6})$/.exec(value);
+    if (!match)
+        return null;
+    return { prefix: match[1].toUpperCase(), number: Number(match[2]) };
+}
+export function formatTaskId(prefix, number) {
+    return `${prefix}-${String(number).padStart(3, "0")}`;
+}
+// A task folder may be spelled T-3 or T-003; both name the same task.
+export function taskIdSpellings(id) {
+    const parsed = parseTaskId(id);
+    if (!parsed)
+        return [id];
+    return [
+        ...new Set([
+            id,
+            formatTaskId(parsed.prefix, parsed.number),
+            `${parsed.prefix}-${parsed.number}`,
+        ]),
+    ];
+}
+// Ids mentioned in free text. `T-<n>` stays case-insensitive as it always was; any other prefix
+// matches only when registered and written upper-case, so "utf-8" or "sha-256" never match.
+export function extractTaskIds(text, prefixes = [LEGACY_PREFIX]) {
+    const ids = new Set();
+    for (const match of text.matchAll(/\bT-(\d+)\b/gi))
+        ids.add(`${LEGACY_PREFIX}-${match[1]}`);
+    // Filtered to [A-Z0-9] by isValidPrefix, so joining into a pattern needs no escaping.
+    const others = [...new Set(prefixes)].filter((prefix) => prefix !== LEGACY_PREFIX && isValidPrefix(prefix));
+    if (others.length)
+        for (const match of text.matchAll(new RegExp(`\\b(${others.join("|")})-(\\d+)\\b`, "g")))
+            ids.add(`${match[1]}-${match[2]}`);
+    return [...ids];
+}
+// A short prefix from a project id: initials of a multi-part id (ocean-language -> OL), else the
+// first three letters (dashboard -> DAS). Taken or reserved candidates get a numeric suffix.
+export function derivePrefix(projectId, taken = []) {
+    const used = new Set([...taken, LEGACY_PREFIX].map((prefix) => prefix.toUpperCase()));
+    const segments = projectId
+        .toUpperCase()
+        .split(/[-._]/)
+        .map((segment) => segment.replace(/[^A-Z0-9]/g, "").replace(/^[0-9]+/, ""))
+        .filter(Boolean);
+    const base = segments.length > 1
+        ? segments
+            .map((segment) => segment[0])
+            .join("")
+            .slice(0, 6)
+        : (segments[0] ?? "P").slice(0, 3);
+    const free = (candidate) => isValidPrefix(candidate) && !used.has(candidate);
+    if (free(base))
+        return base;
+    for (let suffix = 2;; suffix += 1) {
+        const tail = String(suffix);
+        const candidate = `${base.slice(0, 6 - tail.length)}${tail}`;
+        if (free(candidate))
+            return candidate;
+    }
+}
+//# sourceMappingURL=task-id.js.map

package/node_modules/@ocean/core/dist/shared/fs-utils.js

@@ -0,0 +1,212 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { chmod, link, mkdir, readFile, realpath, rename, rm, stat, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { LEGACY_REGISTRY_DIR, oceanPath, REGISTRY_DIR } from "./paths.js";
+// Small filesystem/parsing helpers shared across layers, kept alongside paths.ts rather than
+// under any single layer since both application and infrastructure code use them directly.
+// Atomic write: content lands in a sibling temp file and is renamed into place, so a failure
+// (disk full, OOM kill, thrown error) never leaves the target truncated or partially written.
+// A symlinked target is written through to the file it names, so the link survives, and an
+// existing file keeps its permission bits unless a mode is given (T-296): renaming a fresh
+// temp over a 0600 client config used to leave it at the umask default.
+export async function atomicWrite(target, content, mode) {
+    let destination = target;
+    let keep = mode;
+    try {
+        destination = await realpath(target);
+        if (keep === undefined)
+            keep = (await stat(destination)).mode & 0o7777;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const temp = `${destination}.ocean-tmp-${process.pid}-${Date.now()}`;
+    try {
+        await writeFile(temp, content, { encoding: "utf8", mode: keep });
+        // writeFile's mode is masked by the umask; chmod sets the exact bits.
+        if (keep !== undefined)
+            await chmod(temp, keep);
+        await rename(temp, destination);
+        return Buffer.byteLength(content, "utf8");
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+}
+// Exclusive cross-process lock around a read-modify-write of `target` (T-257): concurrent
+// session closeouts each read a shared file, edit it and write it back, and without a lock
+// the later write drops the earlier one's changes. The lock is `<target>.lock`, holding a
+// token unique to this acquisition. It is created by linking a fully written temp file into
+// place, so it is never seen empty, and released only while it still holds our token.
+const LOCK_WAIT_MS = 10_000;
+const LOCK_RETRY_MS = 20;
+// The sections this guards take milliseconds. A lock older than this belongs to a writer that
+// died or whose pid was reused, and is stale whoever it appears to belong to.
+const LOCK_STALE_MS = 60_000;
+// The takeover guard is only ever held for a read and an unlink.
+const TAKEOVER_STALE_MS = 5_000;
+async function createLockFile(lock, token) {
+    const temp = `${lock}.ocean-tmp-${randomUUID()}`;
+    await writeFile(temp, token, "utf8");
+    try {
+        await link(temp, lock);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+function ownerIsGone(token) {
+    const pid = Number.parseInt(token, 10);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code !== "EPERM";
+    }
+}
+async function staleLockToken(lock) {
+    const token = await readFile(lock, "utf8").catch(() => null);
+    const info = await stat(lock).catch(() => null);
+    if (token === null || info === null)
+        return null;
+    return Date.now() - info.mtimeMs > LOCK_STALE_MS || ownerIsGone(token)
+        ? token
+        : null;
+}
+// Removes a stale lock, but only under a takeover guard and only if the lock still holds the
+// token judged stale: two waiters that both saw the same stale lock can never end up deleting
+// a live lock one of them has just created. Returns whether the stale lock was removed.
+async function removeStaleLock(lock, stale) {
+    const guard = `${lock}.takeover`;
+    if (!(await createLockFile(guard, `${process.pid} ${randomUUID()}`))) {
+        const info = await stat(guard).catch(() => null);
+        if (info && Date.now() - info.mtimeMs > TAKEOVER_STALE_MS)
+            await rm(guard, { force: true });
+        return false;
+    }
+    try {
+        if ((await readFile(lock, "utf8").catch(() => null)) !== stale)
+            return false;
+        await rm(lock, { force: true });
+        return true;
+    }
+    finally {
+        await rm(guard, { force: true });
+    }
+}
+export async function withFileLock(target, run) {
+    const lock = `${target}.lock`;
+    const token = `${process.pid} ${randomUUID()}`;
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    await mkdir(path.dirname(lock), { recursive: true });
+    for (;;) {
+        if (await createLockFile(lock, token))
+            break;
+        const stale = await staleLockToken(lock);
+        if (stale !== null && (await removeStaleLock(lock, stale)))
+            continue;
+        if (Date.now() > deadline)
+            throw new Error(`Lock ${lock} still held after ${LOCK_WAIT_MS} ms`);
+        await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
+    }
+    try {
+        return await run();
+    }
+    finally {
+        if ((await readFile(lock, "utf8").catch(() => null)) === token)
+            await rm(lock, { force: true });
+    }
+}
+// Truncates text to at most `maxBytes` UTF-8 bytes without splitting a code point: a partial
+// trailing sequence is dropped rather than rendered as U+FFFD. Callers compare lengths to
+// detect truncation and append their own marker.
+export function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text) <= maxBytes)
+        return text;
+    if (maxBytes <= 0)
+        return "";
+    return new StringDecoder("utf8").write(Buffer.from(text).subarray(0, maxBytes));
+}
+// Parses JSON that may be malformed or may not be an object (e.g. a bare string/number) —
+// returns null instead of throwing, so a caller reading an untrusted or legacy field never
+// needs its own try/catch.
+export function safeJsonParse(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object"
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Parses a `---\n...\n---` frontmatter block into a flat field map. First occurrence of a
+// key wins; values are trimmed and stripped of one layer of surrounding quotes. Exported for
+// the brain markdown layer (application/brain/brain-markdown.ts), which needs the raw block
+// text too (for nested `metadata:` and block-list `tags:`), not just the flattened map this
+// function returns.
+export function parseFrontmatter(source) {
+    // Normalized up front: a per-line regex below anchors on `$` (end of string), which a
+    // trailing `\r` from CRLF-checked-out files (e.g. a Windows git checkout) defeats — `.`
+    // excludes line terminators, so the line never reaches `$` and silently fails to match.
+    const normalized = source.replace(/\r\n/g, "\n");
+    if (!normalized.startsWith("---"))
+        return {};
+    const end = normalized.indexOf("\n---", 3);
+    const block = end < 0 ? normalized.slice(3) : normalized.slice(3, end);
+    const fields = {};
+    for (const line of block.split("\n")) {
+        const match = /^\s{0,2}([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        if (fields[match[1]] === undefined)
+            fields[match[1]] = match[2].trim().replace(/^["']|["']$/g, "");
+    }
+    return fields;
+}
+// Frontmatter of a record fits in its first 4 KiB; reads stop there.
+export const FRONTMATTER_READ_BYTES = 4_096;
+export async function readFrontmatterFile(file, readBytes) {
+    try {
+        const info = await stat(file);
+        if (!info.isFile())
+            return null;
+        const handle = await readFile(file, "utf8");
+        return {
+            fields: parseFrontmatter(handle.slice(0, readBytes)),
+            mtimeMs: info.mtimeMs,
+            size: info.size,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// Registry files moved out of control-plane/; each one is carried over the first time anything
+// touches it, so no command can create an empty registry that strands the old one.
+export function registryFile(name) {
+    const current = oceanPath(REGISTRY_DIR, name);
+    if (existsSync(current))
+        return current;
+    const legacy = oceanPath(LEGACY_REGISTRY_DIR, name);
+    if (existsSync(legacy)) {
+        mkdirSync(path.dirname(current), { recursive: true });
+        renameSync(legacy, current);
+    }
+    return current;
+}
+//# sourceMappingURL=fs-utils.js.map

package/node_modules/@ocean/core/dist/shared/local-date.js

@@ -0,0 +1,16 @@
+// The calendar date on the machine's own clock, as YYYY-MM-DD. `toISOString()` gives the UTC
+// date instead, which filed anything written 00:00–03:00 in Baghdad under the day before.
+const pad = (value) => String(value).padStart(2, "0");
+export function localDate(now = new Date()) {
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+// HH:MM on the same clock, for stamps that sit next to a localDate.
+export function localTime(now = new Date()) {
+    return `${pad(now.getHours())}:${pad(now.getMinutes())}`;
+}
+// A stored ISO timestamp read back on the local clock; now when it is empty or invalid.
+export function localMoment(iso) {
+    const parsed = new Date(iso ?? "");
+    return Number.isNaN(parsed.getTime()) ? new Date() : parsed;
+}
+//# sourceMappingURL=local-date.js.map