@phren/cli 0.1.8 → 0.1.9

package/dist/agent-launch.d.ts

@@ -0,0 +1 @@
+export declare function runBundledAgentCli(args: string[]): Promise<void>;

package/dist/agent-launch.js

@@ -0,0 +1,48 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { pathToFileURL } from "url";
+import { ROOT } from "./package-metadata.js";
+async function tryImport(candidate) {
+    try {
+        return await import(candidate);
+    }
+    catch {
+        return null;
+    }
+}
+async function loadBundledAgentModule() {
+    const workspaceCandidates = [
+        path.join(ROOT, "..", "agent", "src", "index.ts"),
+        path.join(ROOT, "..", "agent", "dist", "index.js"),
+    ];
+    for (const candidate of workspaceCandidates) {
+        if (!fs.existsSync(candidate))
+            continue;
+        const mod = await tryImport(pathToFileURL(candidate).href);
+        if (mod?.runAgentCli)
+            return mod;
+    }
+    const packageModule = await tryImport("@phren/agent");
+    if (packageModule?.runAgentCli)
+        return packageModule;
+    return null;
+}
+export async function runBundledAgentCli(args) {
+    const mod = await loadBundledAgentModule();
+    if (mod?.runAgentCli) {
+        await mod.runAgentCli(args);
+        return;
+    }
+    try {
+        execFileSync("phren-agent", args, { stdio: "inherit" });
+        return;
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "status" in err) {
+            const status = err.status;
+            process.exit(status ?? 1);
+        }
+        throw new Error("Integrated agent runtime is unavailable. Install or build @phren/agent, or use `phren manage ...` for memory operations.");
+    }
+}

package/dist/auth/profiles.d.ts

@@ -0,0 +1,58 @@
+export type ApiKeyProvider = "openai" | "openrouter" | "anthropic";
+export type AuthProvider = ApiKeyProvider | "openai-codex";
+export interface ApiKeyProfile {
+    id: string;
+    kind: "api-key";
+    provider: ApiKeyProvider;
+    label: string;
+    apiKey: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CodexAuthProfile {
+    id: string;
+    kind: "codex-subscription";
+    provider: "openai-codex";
+    label: string;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    accountId?: string;
+    lastRefresh?: string;
+    source: "phren-oauth" | "codex-cli-import";
+    createdAt: string;
+    updatedAt: string;
+}
+export type AuthProfile = ApiKeyProfile | CodexAuthProfile;
+export declare function authProfilesPath(): string;
+export declare function getAuthProfiles(): AuthProfile[];
+export declare function getApiKeyProfile(provider: ApiKeyProvider): ApiKeyProfile | null;
+export declare function hasApiKeyProfile(provider: ApiKeyProvider): boolean;
+export declare function upsertApiKeyProfile(provider: ApiKeyProvider, apiKey: string): ApiKeyProfile;
+export declare function removeApiKeyProfile(provider: ApiKeyProvider): boolean;
+export declare function resolveApiKey(provider: ApiKeyProvider, envVar: string): string | null;
+export declare function hasCodexCliAuth(): boolean;
+export declare function getCodexAuthProfile(opts?: {
+    allowCliImport?: boolean;
+}): CodexAuthProfile | null;
+export declare function hasCodexAuthProfile(opts?: {
+    allowCliImport?: boolean;
+}): boolean;
+export declare function upsertCodexAuthProfile(data: {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    accountId?: string;
+    lastRefresh?: string;
+    source?: "phren-oauth" | "codex-cli-import";
+}): CodexAuthProfile;
+export declare function removeCodexAuthProfile(): boolean;
+export interface AuthStatusEntry {
+    provider: AuthProvider;
+    configured: boolean;
+    source: "env" | "profile" | "codex-cli" | "none";
+    label: string;
+    expiresAt?: number;
+    accountId?: string;
+}
+export declare function getAuthStatusEntries(): AuthStatusEntry[];

package/dist/auth/profiles.js

@@ -0,0 +1,238 @@
+import * as fs from "fs";
+import * as path from "path";
+import { atomicWriteText, homePath } from "../phren-paths.js";
+const DEFAULT_PROFILE_IDS = {
+    openai: "openai-default",
+    openrouter: "openrouter-default",
+    anthropic: "anthropic-default",
+    "openai-codex": "openai-codex-default",
+};
+function defaultLabel(provider) {
+    switch (provider) {
+        case "openai":
+            return "OpenAI API";
+        case "openrouter":
+            return "OpenRouter API";
+        case "anthropic":
+            return "Anthropic API";
+        case "openai-codex":
+            return "OpenAI Codex Subscription";
+    }
+}
+function authProfileDir() {
+    return homePath(".phren", ".config");
+}
+function authProfilesFilePath() {
+    return path.join(authProfileDir(), "auth-profiles.json");
+}
+function codexCliAuthPath() {
+    return homePath(".codex", "auth.json");
+}
+function ensureAuthProfileDir() {
+    fs.mkdirSync(authProfileDir(), { recursive: true, mode: 0o700 });
+}
+function persistProfiles(data) {
+    ensureAuthProfileDir();
+    const filePath = authProfilesFilePath();
+    atomicWriteText(filePath, JSON.stringify(data, null, 2) + "\n");
+    try {
+        fs.chmodSync(filePath, 0o600);
+    }
+    catch { /* best effort */ }
+}
+function normalizeStore(raw) {
+    if (!raw || typeof raw !== "object") {
+        return { schemaVersion: 1, profiles: [] };
+    }
+    const record = raw;
+    if (record.schemaVersion !== 1 || !Array.isArray(record.profiles)) {
+        return { schemaVersion: 1, profiles: [] };
+    }
+    return {
+        schemaVersion: 1,
+        profiles: record.profiles.filter((profile) => {
+            if (!profile || typeof profile !== "object")
+                return false;
+            const p = profile;
+            return typeof p.id === "string" && typeof p.kind === "string" && typeof p.provider === "string";
+        }),
+    };
+}
+function loadStore() {
+    try {
+        return normalizeStore(JSON.parse(fs.readFileSync(authProfilesFilePath(), "utf8")));
+    }
+    catch {
+        return { schemaVersion: 1, profiles: [] };
+    }
+}
+function upsertProfile(profile) {
+    const store = loadStore();
+    store.profiles = store.profiles.filter((entry) => entry.id !== profile.id);
+    store.profiles.push(profile);
+    persistProfiles(store);
+    return profile;
+}
+export function authProfilesPath() {
+    return authProfilesFilePath();
+}
+export function getAuthProfiles() {
+    return loadStore().profiles;
+}
+export function getApiKeyProfile(provider) {
+    return loadStore().profiles.find((profile) => profile.kind === "api-key" && profile.provider === provider && profile.id === DEFAULT_PROFILE_IDS[provider]) ?? null;
+}
+export function hasApiKeyProfile(provider) {
+    return Boolean(getApiKeyProfile(provider));
+}
+export function upsertApiKeyProfile(provider, apiKey) {
+    const now = new Date().toISOString();
+    const existing = getApiKeyProfile(provider);
+    const profile = {
+        id: DEFAULT_PROFILE_IDS[provider],
+        kind: "api-key",
+        provider,
+        label: defaultLabel(provider),
+        apiKey,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+    };
+    return upsertProfile(profile);
+}
+export function removeApiKeyProfile(provider) {
+    const store = loadStore();
+    const before = store.profiles.length;
+    store.profiles = store.profiles.filter((profile) => !(profile.kind === "api-key" && profile.provider === provider));
+    if (store.profiles.length === before)
+        return false;
+    persistProfiles(store);
+    return true;
+}
+export function resolveApiKey(provider, envVar) {
+    const envValue = process.env[envVar];
+    if (typeof envValue === "string" && envValue.trim())
+        return envValue.trim();
+    return getApiKeyProfile(provider)?.apiKey ?? null;
+}
+function inferCodexExpiry(lastRefresh) {
+    const refreshedAt = lastRefresh ? Date.parse(lastRefresh) : NaN;
+    if (!Number.isNaN(refreshedAt))
+        return refreshedAt + 60 * 60 * 1000;
+    return Date.now() + 60 * 60 * 1000;
+}
+function readCodexCliAuthFile() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(codexCliAuthPath(), "utf8"));
+        const accessToken = typeof parsed.tokens?.access_token === "string" ? parsed.tokens.access_token : null;
+        if (!accessToken)
+            return null;
+        const now = new Date().toISOString();
+        return {
+            id: DEFAULT_PROFILE_IDS["openai-codex"],
+            kind: "codex-subscription",
+            provider: "openai-codex",
+            label: defaultLabel("openai-codex"),
+            accessToken,
+            refreshToken: typeof parsed.tokens?.refresh_token === "string" ? parsed.tokens.refresh_token : undefined,
+            accountId: typeof parsed.tokens?.account_id === "string" ? parsed.tokens.account_id : undefined,
+            expiresAt: inferCodexExpiry(typeof parsed.last_refresh === "string" ? parsed.last_refresh : undefined),
+            lastRefresh: typeof parsed.last_refresh === "string" ? parsed.last_refresh : undefined,
+            source: "codex-cli-import",
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function hasCodexCliAuth() {
+    return Boolean(readCodexCliAuthFile());
+}
+export function getCodexAuthProfile(opts = {}) {
+    const localProfile = loadStore().profiles.find((profile) => profile.kind === "codex-subscription" && profile.provider === "openai-codex") ?? null;
+    if (localProfile)
+        return localProfile;
+    if (!opts.allowCliImport)
+        return null;
+    const imported = readCodexCliAuthFile();
+    if (!imported)
+        return null;
+    return upsertCodexAuthProfile({
+        accessToken: imported.accessToken,
+        refreshToken: imported.refreshToken,
+        expiresAt: imported.expiresAt,
+        accountId: imported.accountId,
+        lastRefresh: imported.lastRefresh,
+        source: "codex-cli-import",
+    });
+}
+export function hasCodexAuthProfile(opts = {}) {
+    if (getCodexAuthProfile({ allowCliImport: false }))
+        return true;
+    return Boolean(opts.allowCliImport && readCodexCliAuthFile());
+}
+export function upsertCodexAuthProfile(data) {
+    const now = new Date().toISOString();
+    const existing = getCodexAuthProfile({ allowCliImport: false });
+    const profile = {
+        id: DEFAULT_PROFILE_IDS["openai-codex"],
+        kind: "codex-subscription",
+        provider: "openai-codex",
+        label: defaultLabel("openai-codex"),
+        accessToken: data.accessToken,
+        refreshToken: data.refreshToken,
+        expiresAt: data.expiresAt,
+        accountId: data.accountId,
+        lastRefresh: data.lastRefresh ?? now,
+        source: data.source ?? "phren-oauth",
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+    };
+    return upsertProfile(profile);
+}
+export function removeCodexAuthProfile() {
+    const store = loadStore();
+    const before = store.profiles.length;
+    store.profiles = store.profiles.filter((profile) => !(profile.kind === "codex-subscription" && profile.provider === "openai-codex"));
+    if (store.profiles.length === before)
+        return false;
+    persistProfiles(store);
+    return true;
+}
+export function getAuthStatusEntries() {
+    const apiProviders = [
+        { provider: "openrouter", envVar: "OPENROUTER_API_KEY" },
+        { provider: "anthropic", envVar: "ANTHROPIC_API_KEY" },
+        { provider: "openai", envVar: "OPENAI_API_KEY" },
+    ];
+    const apiEntries = apiProviders.map(({ provider, envVar }) => {
+        const envValue = process.env[envVar];
+        const profile = getApiKeyProfile(provider);
+        return {
+            provider,
+            configured: Boolean((typeof envValue === "string" && envValue.trim()) || profile),
+            source: (typeof envValue === "string" && envValue.trim())
+                ? "env"
+                : profile
+                    ? "profile"
+                    : "none",
+            label: defaultLabel(provider),
+        };
+    });
+    const localCodex = getCodexAuthProfile({ allowCliImport: false });
+    const cliCodex = localCodex ? null : readCodexCliAuthFile();
+    const codexEntry = {
+        provider: "openai-codex",
+        configured: Boolean(localCodex || cliCodex),
+        source: localCodex
+            ? (localCodex.source === "codex-cli-import" ? "codex-cli" : "profile")
+            : cliCodex
+                ? "codex-cli"
+                : "none",
+        label: defaultLabel("openai-codex"),
+        expiresAt: localCodex?.expiresAt ?? cliCodex?.expiresAt,
+        accountId: localCodex?.accountId ?? cliCodex?.accountId,
+    };
+    return [...apiEntries, codexEntry];
+}

package/dist/cli/cli.js

@@ -13,6 +13,7 @@ import { handleTaskView, handleSessionsView, handleQuickstart, handleDebugInject
 import { handleAddFinding, handleDoctor, handleFragmentSearch, handleMemoryUi, handleTruths, handlePinCanonical, handleQualityFeedback, handleRelatedDocs, handleConsolidationStatus, handleSessionContext, handleSearch, handleShell, handleStatus, handleUpdate, } from "./actions.js";
 import { handleGraphNamespace } from "./graph.js";
 import { resolveRuntimeProfile } from "../runtime-profile.js";
+import { runBundledAgentCli } from "../agent-launch.js";
 // ── CLI router ───────────────────────────────────────────────────────────────
 export async function runCliCommand(command, args) {
     const getProfile = () => resolveRuntimeProfile(getPhrenPath());
@@ -119,14 +120,7 @@ export async function runCliCommand(command, args) {
         case "promote":
             return handlePromoteNamespace(args);
         case "agent": {
-            try {
-                const { runAgentCli } = await import("@phren/agent");
-                return runAgentCli(args);
-            }
-            catch {
-                console.error("@phren/agent is not installed. Install it with: npm i -g @phren/agent");
-                process.exit(1);
-            }
+            return runBundledAgentCli(args);
         }
         default:
             console.error(`Unknown command: ${command}\nRun 'phren --help' for available commands.`);

package/dist/entrypoint.d.ts

@@ -1 +1,21 @@
-export declare function runTopLevelCommand(argv: string[]): Promise<boolean>;
+export declare const CLI_COMMANDS: string[];
+export type TopLevelInvocation = {
+    kind: "agent";
+    argv: string[];
+} | {
+    kind: "manage";
+    argv: string[];
+} | {
+    kind: "mcp";
+    phrenArg: string;
+} | {
+    kind: "help";
+} | {
+    kind: "version";
+};
+export declare function resolveTopLevelInvocation(argv: string[]): TopLevelInvocation;
+export declare function printIntegratedHelp(): void;
+export declare function printIntegratedVersion(): void;
+export declare function runTopLevelCommand(argv: string[], opts?: {
+    allowDefaultShell?: boolean;
+}): Promise<boolean>;

package/dist/entrypoint.js

@@ -3,31 +3,67 @@ import * as path from "path";
 import { parseMcpMode, runInit } from "./init/init.js";
 import { errorMessage } from "./utils.js";
 import { logger } from "./logger.js";
-import { defaultPhrenPath, findPhrenPath } from "./shared.js";
+import { defaultPhrenPath, expandHomePath, findPhrenPath, readRootManifest } from "./shared.js";
+import { VERSION } from "./package-metadata.js";
 import { addProjectFromPath } from "./core/project.js";
 import { PROJECT_OWNERSHIP_MODES, getProjectOwnershipDefault, parseProjectOwnershipMode, } from "./project-config.js";
-const HELP_TEXT = `phren - persistent knowledge for your agents
+const HELP_TEXT = `phren manage - memory, setup, and store operations
 
-  phren                     Interactive shell
-  phren init                Set up phren
-  phren quickstart          Quick setup: init + project scaffold
-  phren add [path]          Register a project
-  phren search <query>      Search what phren knows
-  phren status              Health check
-  phren doctor [--fix]      Diagnose and repair
-  phren web-ui              Open the knowledge graph
-  phren tasks               Cross-project task view
-  phren graph               Fragment knowledge graph
-  phren agent <task>        Run the coding agent
-  phren agent -i            Interactive agent TUI
+  phren manage init                Set up phren
+  phren manage quickstart          Quick setup: init + project scaffold
+  phren manage add [path]          Register a project
+  phren manage search <query>      Search what phren knows
+  phren manage status              Health check
+  phren manage doctor [--fix]      Diagnose and repair
+  phren manage web-ui              Open the knowledge graph
+  phren manage tasks               Cross-project task view
+  phren manage graph               Fragment knowledge graph
+  phren manage shell               Interactive memory shell
 
-  phren store list              List registered stores
-  phren team init <name>        Create a team store
+Agent shortcuts:
+  phren                            Interactive coding agent
+  phren "fix the login bug"        One-shot coding task
+  phren --provider openai-codex -i Interactive agent with explicit provider
+  phren --reasoning high "..."     Run GPT-5.4 with higher reasoning
 
-  phren help <topic>        Detailed help for a topic
+Legacy shortcuts still work:
+  phren init, phren search, phren task, phren config, ...
 
+  phren manage help <topic>        Detailed management help
 Topics: projects, skills, hooks, config, maintain, setup, stores, team, env, all
 `;
+const INTEGRATED_HELP_TEXT = `phren - persistent memory with an integrated coding agent
+
+Agent:
+  phren                            Interactive coding agent
+  phren "fix the login bug"        One-shot coding task
+  phren -i                         Interactive agent TUI
+  phren --provider openai-codex "..."  Run the agent with an explicit provider
+  phren --reasoning high "..."         Override the default medium thinking level
+  phren agent ...                  Explicit alias for agent mode
+  phren auth status                Show configured provider auth
+  phren auth login                 Sign in with your Codex subscription
+
+Memory and management:
+  phren manage <command>           Memory/store/setup/config operations
+  phren mem <command>              Alias for \`phren manage\`
+  phren manage shell               Interactive memory shell
+  phren manage search <query>      Search what phren knows
+  phren manage task add <project> "..."
+  phren manage config ...
+  phren manage init
+
+Legacy shortcuts still work:
+  phren init
+  phren search <query>
+  phren task ...
+  phren config ...
+  phren store ...
+
+Machine-facing mode:
+  phren <phren-root-path>          Start the MCP server over stdio
+
+Use \`phren manage help\` for the full management command reference.`;
 const HELP_TOPICS = {
     projects: `Projects:
   phren add [path] [--ownership <mode>]   Register a project
@@ -145,7 +181,7 @@ Usage:
 
 ${Object.values(HELP_TOPICS).join("\n")}`;
 }
-const CLI_COMMANDS = [
+export const CLI_COMMANDS = [
     "search",
     "shell",
     "update",
@@ -191,6 +227,70 @@ const CLI_COMMANDS = [
     "promote",
     "agent",
 ];
+const DIRECT_MANAGE_COMMANDS = new Set([
+    "add",
+    "init",
+    "uninstall",
+    "status",
+    "verify",
+    "mcp-mode",
+    "hooks-mode",
+    "link",
+    "--health",
+    ...CLI_COMMANDS,
+]);
+function looksLikePhrenRootArg(arg) {
+    if (!arg || arg.startsWith("-"))
+        return false;
+    try {
+        const resolved = path.resolve(expandHomePath(arg));
+        return fs.existsSync(resolved) && Boolean(readRootManifest(resolved));
+    }
+    catch {
+        return false;
+    }
+}
+function firstPositionalArg(argv) {
+    return argv.find((arg) => !arg.startsWith("-"));
+}
+export function resolveTopLevelInvocation(argv) {
+    const argvCommand = argv[0];
+    const positional = firstPositionalArg(argv);
+    if (looksLikePhrenRootArg(positional)) {
+        return { kind: "mcp", phrenArg: positional };
+    }
+    if (argvCommand === "--help" || argvCommand === "-h") {
+        return { kind: "help" };
+    }
+    if (argvCommand === "--version" || argvCommand === "-v" || argvCommand === "version") {
+        return { kind: "version" };
+    }
+    if (argvCommand === "help") {
+        return argv.length > 1 ? { kind: "manage", argv } : { kind: "help" };
+    }
+    if (argvCommand === "manage" || argvCommand === "mem") {
+        return { kind: "manage", argv: argv.slice(1).length > 0 ? argv.slice(1) : ["help"] };
+    }
+    if (argvCommand === "agent") {
+        return { kind: "agent", argv: argv.slice(1) };
+    }
+    if (argvCommand === "auth") {
+        return { kind: "agent", argv };
+    }
+    if (!argvCommand) {
+        return { kind: "agent", argv: ["-i"] };
+    }
+    if (DIRECT_MANAGE_COMMANDS.has(argvCommand)) {
+        return { kind: "manage", argv };
+    }
+    return { kind: "agent", argv };
+}
+export function printIntegratedHelp() {
+    console.log(INTEGRATED_HELP_TEXT);
+}
+export function printIntegratedVersion() {
+    console.log(`phren v${VERSION}`);
+}
 async function flushTopLevelOutput() {
     await Promise.all([
         new Promise((resolve) => process.stdout.write("", () => resolve())),
@@ -254,7 +354,7 @@ async function promptProjectOwnership(phrenPath, fallback) {
         });
     });
 }
-export async function runTopLevelCommand(argv) {
+export async function runTopLevelCommand(argv, opts = {}) {
     const argvCommand = argv[0];
     if (argvCommand === "--help" || argvCommand === "-h" || argvCommand === "help") {
         const topic = argv[1]?.toLowerCase();
@@ -429,6 +529,10 @@ export async function runTopLevelCommand(argv) {
         return finish();
     }
     if (!argvCommand && process.stdin.isTTY && process.stdout.isTTY) {
+        if (opts.allowDefaultShell === false) {
+            console.log(HELP_TEXT);
+            return finish();
+        }
         const { runCliCommand } = await import("./cli/cli.js");
         await runCliCommand("shell", []);
         return finish();

package/dist/index.js

@@ -21,15 +21,29 @@ import { register as registerExtract } from "./tools/extract.js";
 import { register as registerConfig } from "./tools/config.js";
 import { mcpResponse } from "./tools/types.js";
 import { errorMessage } from "./utils.js";
-import { runTopLevelCommand } from "./entrypoint.js";
+import { printIntegratedHelp, printIntegratedVersion, resolveTopLevelInvocation, runTopLevelCommand, } from "./entrypoint.js";
 import { startEmbeddingWarmup } from "./startup-embedding.js";
 import { resolveRuntimeProfile } from "./runtime-profile.js";
 import { VERSION as PACKAGE_VERSION } from "./package-metadata.js";
-const handledTopLevelCommand = await runTopLevelCommand(process.argv.slice(2));
-// MCP mode: first non-flag arg is the phren path. Resolve it lazily so CLI commands
-// like `maintain` are not misinterpreted as a filesystem path after the command has run.
-const phrenArg = handledTopLevelCommand ? undefined : process.argv.find((a, i) => i >= 2 && !a.startsWith("-"));
-const phrenPath = handledTopLevelCommand ? "" : findPhrenPathWithArg(phrenArg);
+import { runBundledAgentCli } from "./agent-launch.js";
+const invocation = resolveTopLevelInvocation(process.argv.slice(2));
+if (invocation.kind === "help") {
+    printIntegratedHelp();
+    process.exit(0);
+}
+if (invocation.kind === "version") {
+    printIntegratedVersion();
+    process.exit(0);
+}
+if (invocation.kind === "manage") {
+    await runTopLevelCommand(invocation.argv, { allowDefaultShell: false });
+    process.exit(process.exitCode ?? 0);
+}
+if (invocation.kind === "agent") {
+    await runBundledAgentCli(invocation.argv);
+    process.exit(process.exitCode ?? 0);
+}
+const phrenPath = findPhrenPathWithArg(invocation.phrenArg);
 const STALE_LOCK_MS = 120_000; // 2 min — slightly above EXEC_TIMEOUT_MS (30s) to avoid blocking healthy writers
 function cleanStaleLocks(phrenPath) {
     const dir = runtimeDir(phrenPath);
@@ -222,9 +236,7 @@ async function main() {
     process.on("SIGTERM", () => void shutdown("SIGTERM"));
     process.on("SIGINT", () => void shutdown("SIGINT"));
 }
-if (!handledTopLevelCommand) {
-    main().catch((err) => {
-        console.error("Failed to start phren-mcp:", err);
-        process.exit(1);
-    });
-}
+main().catch((err) => {
+    console.error("Failed to start phren-mcp:", err);
+    process.exit(1);
+});

package/dist/session/artifacts.d.ts

@@ -0,0 +1,44 @@
+import { type SessionState } from "./utils.js";
+export type SessionCounterField = "findingsAdded" | "tasksCompleted";
+export interface SessionSummaryRecord {
+    summary: string;
+    sessionId: string;
+    project?: string;
+    endedAt?: string;
+}
+export interface SessionSummaryLookup {
+    summary: string | null;
+    sessionId?: string;
+    project?: string;
+    endedAt?: string;
+}
+export interface SerializedSessionMessage {
+    role: string;
+    content: unknown;
+}
+export interface SessionMessagesSnapshot {
+    schemaVersion: 1;
+    sessionId: string;
+    project?: string;
+    savedAt: string;
+    messages: SerializedSessionMessage[];
+}
+interface StartSessionOptions {
+    sessionId?: string;
+    project?: string;
+    agentScope?: string;
+    hookCreated?: boolean;
+    agentCreated?: boolean;
+}
+export declare function lastSummaryPath(phrenPath: string): string;
+export declare function readLastSummary(phrenPath: string): SessionSummaryRecord | null;
+export declare function writeLastSummary(phrenPath: string, record: SessionSummaryRecord): void;
+export declare function findMostRecentSummaryWithProject(phrenPath: string, project?: string): SessionSummaryLookup;
+export declare function startSessionRecord(phrenPath: string, options?: StartSessionOptions): string;
+export declare function readSessionState(phrenPath: string, sessionId: string): SessionState | null;
+export declare function endSessionRecord(phrenPath: string, sessionId: string, summary?: string): void;
+export declare function incrementSessionStateCounter(phrenPath: string, sessionId: string, field: SessionCounterField, count?: number): void;
+export declare function saveSessionMessages(phrenPath: string, sessionId: string, messages: SerializedSessionMessage[], project?: string): void;
+export declare function loadLastSessionSnapshot(phrenPath: string, project?: string): SessionMessagesSnapshot | null;
+export declare function loadLastSessionMessages(phrenPath: string, project?: string): SerializedSessionMessage[] | null;
+export {};

package/dist/session/artifacts.js

@@ -0,0 +1,259 @@
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { withFileLock } from "../shared/governance.js";
+import { atomicWriteJson, debugError, readSessionStateFile, scanSessionFiles, sessionFileForId, sessionsDir, writeSessionStateFile, } from "./utils.js";
+function normalizeSummary(summary) {
+    const trimmed = summary?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function sessionMessagesFileForId(phrenPath, sessionId) {
+    return path.join(sessionsDir(phrenPath), `session-${sessionId}-messages.json`);
+}
+function inferProjectForSession(phrenPath, sessionId) {
+    return readSessionState(phrenPath, sessionId)?.project;
+}
+function inferSavedAt(filePath) {
+    try {
+        return new Date(fs.statSync(filePath).mtimeMs).toISOString();
+    }
+    catch {
+        return new Date(0).toISOString();
+    }
+}
+function extractSessionIdFromMessageFile(filePath) {
+    const match = path.basename(filePath).match(/^session-(.+)-messages\.json$/);
+    return match?.[1] ?? "unknown";
+}
+function parseSessionMessagesSnapshot(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        if (Array.isArray(parsed)) {
+            return {
+                schemaVersion: 1,
+                sessionId: extractSessionIdFromMessageFile(filePath),
+                savedAt: inferSavedAt(filePath),
+                messages: parsed,
+            };
+        }
+        if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.messages)) {
+            return null;
+        }
+        return {
+            schemaVersion: 1,
+            sessionId: typeof parsed.sessionId === "string" ? parsed.sessionId : extractSessionIdFromMessageFile(filePath),
+            project: typeof parsed.project === "string" ? parsed.project : undefined,
+            savedAt: typeof parsed.savedAt === "string" ? parsed.savedAt : inferSavedAt(filePath),
+            messages: parsed.messages,
+        };
+    }
+    catch (err) {
+        debugError("parseSessionMessagesSnapshot", err);
+        return null;
+    }
+}
+function listSessionMessageSnapshots(phrenPath) {
+    const dir = sessionsDir(phrenPath);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        debugError("listSessionMessageSnapshots readdir", err);
+        return [];
+    }
+    const snapshots = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.startsWith("session-") || !entry.name.endsWith("-messages.json"))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        const snapshot = parseSessionMessagesSnapshot(fullPath);
+        if (!snapshot)
+            continue;
+        let mtimeMs = 0;
+        try {
+            mtimeMs = fs.statSync(fullPath).mtimeMs;
+        }
+        catch {
+            mtimeMs = 0;
+        }
+        snapshots.push({ snapshot, mtimeMs });
+    }
+    snapshots.sort((a, b) => {
+        const bySavedAt = Date.parse(b.snapshot.savedAt) - Date.parse(a.snapshot.savedAt);
+        if (!Number.isNaN(bySavedAt) && bySavedAt !== 0)
+            return bySavedAt;
+        return b.mtimeMs - a.mtimeMs;
+    });
+    return snapshots;
+}
+export function lastSummaryPath(phrenPath) {
+    return path.join(sessionsDir(phrenPath), "last-summary.json");
+}
+export function readLastSummary(phrenPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lastSummaryPath(phrenPath), "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        if (typeof parsed.summary !== "string" || typeof parsed.sessionId !== "string")
+            return null;
+        return {
+            summary: parsed.summary,
+            sessionId: parsed.sessionId,
+            project: typeof parsed.project === "string" ? parsed.project : undefined,
+            endedAt: typeof parsed.endedAt === "string" ? parsed.endedAt : undefined,
+        };
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            debugError("readLastSummary", err);
+        }
+        return null;
+    }
+}
+export function writeLastSummary(phrenPath, record) {
+    try {
+        atomicWriteJson(lastSummaryPath(phrenPath), {
+            summary: record.summary,
+            sessionId: record.sessionId,
+            project: record.project,
+            endedAt: record.endedAt ?? new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        debugError("writeLastSummary", err);
+    }
+}
+export function findMostRecentSummaryWithProject(phrenPath, project) {
+    const fastPath = readLastSummary(phrenPath);
+    if (fastPath && (!project || fastPath.project === project)) {
+        return fastPath;
+    }
+    const dir = sessionsDir(phrenPath);
+    const results = scanSessionFiles(dir, readSessionStateFile, (state) => typeof state.summary === "string" && state.summary.trim().length > 0, { errorScope: "findMostRecentSummaryWithProject" });
+    if (!project) {
+        if (results.length === 0)
+            return { summary: null };
+        const best = results[0].data;
+        return {
+            summary: best.summary ?? null,
+            sessionId: best.sessionId,
+            project: best.project,
+            endedAt: best.endedAt,
+        };
+    }
+    const projectMatch = results.find(({ data }) => data.project === project);
+    if (projectMatch) {
+        return {
+            summary: projectMatch.data.summary ?? null,
+            sessionId: projectMatch.data.sessionId,
+            project: projectMatch.data.project,
+            endedAt: projectMatch.data.endedAt,
+        };
+    }
+    if (results.length === 0)
+        return { summary: null };
+    const fallback = results[0].data;
+    return {
+        summary: fallback.summary ?? null,
+        sessionId: fallback.sessionId,
+        project: fallback.project,
+        endedAt: fallback.endedAt,
+    };
+}
+export function startSessionRecord(phrenPath, options = {}) {
+    const sessionId = options.sessionId ?? crypto.randomUUID();
+    const state = {
+        sessionId,
+        project: options.project,
+        agentScope: options.agentScope,
+        startedAt: new Date().toISOString(),
+        findingsAdded: 0,
+        tasksCompleted: 0,
+        hookCreated: options.hookCreated,
+        agentCreated: options.agentCreated,
+    };
+    writeSessionStateFile(sessionFileForId(phrenPath, sessionId), state);
+    return sessionId;
+}
+export function readSessionState(phrenPath, sessionId) {
+    return readSessionStateFile(sessionFileForId(phrenPath, sessionId));
+}
+export function endSessionRecord(phrenPath, sessionId, summary) {
+    const file = sessionFileForId(phrenPath, sessionId);
+    if (!fs.existsSync(file))
+        return;
+    const normalizedSummary = normalizeSummary(summary);
+    try {
+        withFileLock(file, () => {
+            const current = readSessionStateFile(file);
+            if (!current)
+                return;
+            const nextState = {
+                ...current,
+                endedAt: new Date().toISOString(),
+                summary: normalizedSummary ?? current.summary,
+                findingsAdded: Number.isFinite(current.findingsAdded) ? current.findingsAdded : 0,
+                tasksCompleted: Number.isFinite(current.tasksCompleted) ? current.tasksCompleted : 0,
+            };
+            writeSessionStateFile(file, nextState);
+            if (normalizedSummary) {
+                writeLastSummary(phrenPath, {
+                    summary: normalizedSummary,
+                    sessionId,
+                    project: nextState.project,
+                    endedAt: nextState.endedAt,
+                });
+            }
+        });
+    }
+    catch (err) {
+        debugError("endSessionRecord", err);
+    }
+}
+export function incrementSessionStateCounter(phrenPath, sessionId, field, count = 1) {
+    const file = sessionFileForId(phrenPath, sessionId);
+    if (!fs.existsSync(file))
+        return;
+    try {
+        withFileLock(file, () => {
+            const current = readSessionStateFile(file);
+            if (!current)
+                return;
+            const currentValue = Number.isFinite(current[field]) ? current[field] : 0;
+            writeSessionStateFile(file, {
+                ...current,
+                findingsAdded: Number.isFinite(current.findingsAdded) ? current.findingsAdded : 0,
+                tasksCompleted: Number.isFinite(current.tasksCompleted) ? current.tasksCompleted : 0,
+                [field]: currentValue + count,
+            });
+        });
+    }
+    catch (err) {
+        debugError(`incrementSessionStateCounter(${field})`, err);
+    }
+}
+export function saveSessionMessages(phrenPath, sessionId, messages, project) {
+    const snapshot = {
+        schemaVersion: 1,
+        sessionId,
+        project: project ?? inferProjectForSession(phrenPath, sessionId),
+        savedAt: new Date().toISOString(),
+        messages,
+    };
+    atomicWriteJson(sessionMessagesFileForId(phrenPath, sessionId), snapshot);
+}
+export function loadLastSessionSnapshot(phrenPath, project) {
+    const snapshots = listSessionMessageSnapshots(phrenPath);
+    if (snapshots.length === 0)
+        return null;
+    if (project) {
+        const projectSnapshot = snapshots.find(({ snapshot }) => snapshot.project === project);
+        if (projectSnapshot)
+            return projectSnapshot.snapshot;
+    }
+    return snapshots[0]?.snapshot ?? null;
+}
+export function loadLastSessionMessages(phrenPath, project) {
+    return loadLastSessionSnapshot(phrenPath, project)?.messages ?? null;
+}

package/dist/session/utils.d.ts

@@ -14,9 +14,12 @@ export interface SessionState {
     tasksCompleted: number;
     /** When true, this session was created by a lifecycle hook, not an explicit MCP call. */
     hookCreated?: boolean;
+    /** When true, this session was created by the coding agent runtime. */
+    agentCreated?: boolean;
 }
 export declare function sessionsDir(phrenPath: string): string;
 export declare function sessionFileForId(phrenPath: string, sessionId: string): string;
+export declare function isSessionStateFileName(name: string): boolean;
 export declare function readSessionStateFile(file: string): SessionState | null;
 export declare function writeSessionStateFile(file: string, state: SessionState): void;
 /**

package/dist/session/utils.js

@@ -19,6 +19,11 @@ export function sessionsDir(phrenPath) {
 export function sessionFileForId(phrenPath, sessionId) {
     return path.join(sessionsDir(phrenPath), `session-${sessionId}.json`);
 }
+export function isSessionStateFileName(name) {
+    return name.startsWith("session-") &&
+        name.endsWith(".json") &&
+        !name.endsWith("-messages.json");
+}
 export function readSessionStateFile(file) {
     try {
         return JSON.parse(fs.readFileSync(file, "utf-8"));
@@ -63,7 +68,7 @@ export function scanSessionFiles(dir, parse, filter, opts) {
     }
     const results = [];
     for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.startsWith("session-") || !entry.name.endsWith(".json"))
+        if (!entry.isFile() || !isSessionStateFileName(entry.name))
             continue;
         const fullPath = path.join(dir, entry.name);
         try {

package/dist/status.js

@@ -15,7 +15,7 @@ import { RESET, BOLD, DIM, GREEN, YELLOW, RED, CYAN } from "./shell/render.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function readPackageVersion() {
     try {
-        const pkgPath = path.resolve(__dirname, "..", "..", "package.json");
+        const pkgPath = path.resolve(__dirname, "..", "package.json");
         const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
         return typeof pkg.version === "string" ? pkg.version : "unknown";
     }

package/dist/tools/session.js

@@ -14,8 +14,9 @@ import { readTasks } from "../data/tasks.js";
 import { readFindings } from "../data/access.js";
 import { getActiveTaskForSession } from "../task/lifecycle.js";
 import { listTaskCheckpoints, writeTaskCheckpoint } from "../session/checkpoints.js";
+import { findMostRecentSummaryWithProject as findMostRecentSummaryRecord, writeLastSummary as writeLastSummaryRecord, } from "../session/artifacts.js";
 import { markImpactEntriesCompletedForSession } from "../finding/impact.js";
-import { atomicWriteJson, debugError, scanSessionFiles, sessionsDir, sessionFileForId, readSessionStateFile, writeSessionStateFile, } from "../session/utils.js";
+import { debugError, scanSessionFiles, sessionsDir, sessionFileForId, readSessionStateFile, writeSessionStateFile, } from "../session/utils.js";
 import { getRuntimeHealth } from "../governance/policy.js";
 import { getProjectSourcePath, readProjectConfig } from "../project-config.js";
 const STALE_SESSION_MS = 24 * 60 * 60 * 1000; // 24 hours
@@ -127,18 +128,9 @@ export function resolveActiveSessionScope(phrenPath, project) {
     }
     return normalizeMemoryScope(bestState?.agentScope);
 }
-/** Path for the last-summary fast-path file. */
-function lastSummaryPath(phrenPath) {
-    return path.join(sessionsDir(phrenPath), "last-summary.json");
-}
 /** Write the last summary for fast retrieval by next session_start. */
 function writeLastSummary(phrenPath, summary, sessionId, project) {
-    try {
-        atomicWriteJson(lastSummaryPath(phrenPath), { summary, sessionId, project, endedAt: new Date().toISOString() });
-    }
-    catch (err) {
-        debugError("writeLastSummary", err);
-    }
+    writeLastSummaryRecord(phrenPath, { summary, sessionId, project, endedAt: new Date().toISOString() });
 }
 /** Find the most recent session with a summary (including ended sessions).
  * @internal Exported for tests. */
@@ -147,25 +139,12 @@ export function findMostRecentSummary(phrenPath) {
 }
 /** Find the most recent session with a summary and project context. */
 function findMostRecentSummaryWithProject(phrenPath) {
-    // Fast path: read from dedicated last-summary file
-    try {
-        const data = JSON.parse(fs.readFileSync(lastSummaryPath(phrenPath), "utf-8"));
-        if (data.summary)
-            return { summary: data.summary, project: data.project, endedAt: data.endedAt };
-    }
-    catch (err) {
-        // ENOENT is expected when no summary has been written yet
-        if (err.code !== "ENOENT") {
-            debugError("findMostRecentSummaryWithProject fastPath", err);
-        }
-    }
-    // Slow path: scan all session files
-    const dir = sessionsDir(phrenPath);
-    const results = scanSessionFiles(dir, readSessionStateFile, (state) => !!state.summary, { errorScope: "findMostRecentSummaryWithProject" });
-    if (results.length === 0)
-        return { summary: null };
-    const best = results[0]; // already sorted newest-mtime-first
-    return { summary: best.data.summary, project: best.data.project, endedAt: best.data.endedAt };
+    const result = findMostRecentSummaryRecord(phrenPath);
+    return {
+        summary: result.summary,
+        project: result.project,
+        endedAt: result.endedAt,
+    };
 }
 /** Resolve session file from an explicit sessionId or a previously-bound connectionId. */
 function resolveSessionFile(phrenPath, sessionId, connectionId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phren/cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
   "type": "module",
   "bin": {
@@ -39,10 +39,18 @@
       "types": "./dist/core/finding.d.ts",
       "default": "./dist/core/finding.js"
     },
+    "./auth/profiles": {
+      "types": "./dist/auth/profiles.d.ts",
+      "default": "./dist/auth/profiles.js"
+    },
     "./session/utils": {
       "types": "./dist/session/utils.d.ts",
       "default": "./dist/session/utils.js"
     },
+    "./session/artifacts": {
+      "types": "./dist/session/artifacts.d.ts",
+      "default": "./dist/session/artifacts.js"
+    },
     "./shell/render-api": {
       "types": "./dist/shell/render-api.d.ts",
       "default": "./dist/shell/render-api.js"