@promptbook/cli 0.113.0-8 → 0.114.0-0

package/apps/agents-server/src/{components/Homepage → utils/agentOrganization}/hiddenFolders.ts

@@ -1,24 +1,53 @@
-import type { AgentOrganizationAgent, AgentOrganizationFolder } from '../../utils/agentOrganization/types';
-import { buildFolderMaps, collectDescendantFolderIds } from './agentOrganizationUtils';
+import { buildFolderTree, collectDescendantFolderIds } from './folderTree';
 
 /**
- * Prefix that marks a folder as hidden from default homepage listings.
+ * Prefix that marks a folder as hidden from default organization listings.
  *
  * Folders whose name starts with this prefix (for example `.core`) are excluded
- * from the agents list, graph, and office views unless the user explicitly toggles
- * hidden-folder visibility on.
+ * from default agent/folder listings unless the caller explicitly opts into showing them.
  *
- * @private function of AgentsList
+ * @private shared hidden-folder helper for Agents Server
  */
 export const HIDDEN_FOLDER_NAME_PREFIX = '.';
 
+/**
+ * Minimal folder shape required by the hidden-folder utilities.
+ *
+ * @private shared hidden-folder helper for Agents Server
+ */
+type HiddenFolderTreeFolder = {
+    readonly id: number;
+    readonly name: string;
+    readonly parentId: number | null;
+};
+
+/**
+ * Minimal agent shape required by the hidden-folder utilities.
+ *
+ * @private shared hidden-folder helper for Agents Server
+ */
+type HiddenFolderTreeAgent = {
+    readonly folderId: number | null;
+};
+
+/**
+ * Result of removing hidden folders and their agents from one organization snapshot.
+ *
+ * @private shared hidden-folder helper for Agents Server
+ */
+type FilterHiddenFolderTreeResult<TFolder extends HiddenFolderTreeFolder, TAgent extends HiddenFolderTreeAgent> = {
+    readonly folders: TFolder[];
+    readonly agents: TAgent[];
+    readonly hasHiddenFolders: boolean;
+};
+
 /**
  * Determines whether one folder name represents a hidden folder.
  *
  * @param folderName - Folder name persisted in the database.
  * @returns True when the folder should be hidden by default.
  *
- * @private function of AgentsList
+ * @private shared hidden-folder helper for Agents Server
  */
 export function isHiddenFolderName(folderName: string): boolean {
     return folderName.startsWith(HIDDEN_FOLDER_NAME_PREFIX);
@@ -34,10 +63,10 @@ export function isHiddenFolderName(folderName: string): boolean {
  * @param folders - All folders in the organization.
  * @returns Set of folder identifiers that should be excluded from default views.
  *
- * @private function of AgentsList
+ * @private shared hidden-folder helper for Agents Server
  */
-export function collectHiddenFolderIds(folders: ReadonlyArray<AgentOrganizationFolder>): Set<number> {
-    const folderMaps = buildFolderMaps(folders);
+export function collectHiddenFolderIds(folders: ReadonlyArray<HiddenFolderTreeFolder>): Set<number> {
+    const folderTree = buildFolderTree(Array.from(folders));
     const hiddenFolderIds = new Set<number>();
 
     for (const folder of folders) {
@@ -45,7 +74,7 @@ export function collectHiddenFolderIds(folders: ReadonlyArray<AgentOrganizationF
             continue;
         }
 
-        for (const descendantId of collectDescendantFolderIds(folder.id, folderMaps.childrenByParentId)) {
+        for (const descendantId of collectDescendantFolderIds(folder.id, folderTree.childrenByParentId)) {
             hiddenFolderIds.add(descendantId);
         }
     }
@@ -53,37 +82,28 @@ export function collectHiddenFolderIds(folders: ReadonlyArray<AgentOrganizationF
     return hiddenFolderIds;
 }
 
-/**
- * Result of removing hidden folders and their agents from one organization snapshot.
- *
- * @private function of AgentsList
- */
-type FilterHiddenFolderTreeResult = {
-    readonly folders: AgentOrganizationFolder[];
-    readonly agents: AgentOrganizationAgent[];
-    readonly hasHiddenFolders: boolean;
-};
-
 /**
  * Removes hidden folders and their agents from one organization snapshot.
  *
  * When `isHiddenFoldersVisible` is true the snapshot passes through unchanged so the
  * caller can render every folder. When false, all hidden folders (including their
- * descendants and the agents inside them) are removed in one pass — keeping the
- * single filtering rule in one place across list, graph, and office views.
+ * descendants and the agents inside them) are removed in one pass.
  *
  * @param folders - All folders in the organization.
  * @param agents - All agents in the organization.
  * @param isHiddenFoldersVisible - Whether the user has opted to display hidden folders.
  * @returns Filtered organization snapshot together with the unfiltered detection flag.
  *
- * @private function of AgentsList
+ * @private shared hidden-folder helper for Agents Server
  */
-export function filterHiddenFolderTree(
-    folders: ReadonlyArray<AgentOrganizationFolder>,
-    agents: ReadonlyArray<AgentOrganizationAgent>,
+export function filterHiddenFolderTree<
+    TFolder extends HiddenFolderTreeFolder,
+    TAgent extends HiddenFolderTreeAgent,
+>(
+    folders: ReadonlyArray<TFolder>,
+    agents: ReadonlyArray<TAgent>,
     isHiddenFoldersVisible: boolean,
-): FilterHiddenFolderTreeResult {
+): FilterHiddenFolderTreeResult<TFolder, TAgent> {
     const hasHiddenFolders = folders.some((folder) => isHiddenFolderName(folder.name));
 
     if (isHiddenFoldersVisible || !hasHiddenFolders) {

package/apps/agents-server/src/utils/agentOwnership.ts

@@ -1,7 +1,7 @@
 import { $getTableName } from '../database/$getTableName';
 import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
 import type { AgentsServerDatabase } from '../database/schema';
-import { buildAgentNameOrIdFilter } from './agentIdentifier';
+import { buildAgentNameOrIdFilter, isSameAgentPermanentId } from './agentIdentifier';
 
 /**
  * Agent row shape used by owner-aware helpers.
@@ -116,7 +116,7 @@ const OWNED_AGENT_ROW_COLUMNS =
  * Disambiguates a list of agent rows that all matched the same identifier.
  *
  * Resolution order:
- * 1. Exact `permanentId` match — always preferred because permanent ids are unique.
+ * 1. Case-insensitive `permanentId` match — always preferred because permanent ids are unique.
  * 2. Single `agentName` match — preserves the legacy lookup by human-readable name.
  * 3. Single remaining row — accepts the only candidate found.
  *
@@ -134,7 +134,7 @@ function pickAgentRowByIdentifier(
         return null;
     }
 
-    const permanentIdMatch = rows.find((row) => row.permanentId === identifier);
+    const permanentIdMatch = rows.find((row) => isSameAgentPermanentId(row.permanentId, identifier));
     if (permanentIdMatch) {
         return permanentIdMatch;
     }

package/apps/agents-server/src/utils/agentProjects/AgentProjectInfo.ts

@@ -0,0 +1,153 @@
+/**
+ * Metadata of one agent-owned project folder.
+ *
+ * A project is one direct child directory of the agent's `projects/` folder which the agent
+ * fully controls — it can create, read, modify, and delete any file inside it, run scripts
+ * there, and optionally turn the folder into a git repository.
+ */
+export type AgentProjectInfo = {
+    /**
+     * Directory name of the project inside the agent `projects/` folder.
+     */
+    readonly projectName: string;
+
+    /**
+     * User-facing name of the project, resolved from the README heading when available.
+     */
+    readonly displayName: string;
+
+    /**
+     * Short project description resolved from the first README paragraph.
+     */
+    readonly description: string;
+
+    /**
+     * Original README filename used for the project profile, or `null` when there is no README.
+     */
+    readonly readmeFileName: string | null;
+
+    /**
+     * Path of the project relative to the agent folder root, for example `projects/my-website`.
+     */
+    readonly relativePath: string;
+
+    /**
+     * Absolute path of the project directory on the Agents Server disk.
+     */
+    readonly absolutePath: string;
+
+    /**
+     * Total size of all files inside the project in bytes.
+     */
+    readonly sizeBytes: number;
+
+    /**
+     * Total count of files inside the project.
+     */
+    readonly fileCount: number;
+
+    /**
+     * Whether the project folder is a git repository (contains a `.git` directory).
+     */
+    readonly isGitRepository: boolean;
+
+    /**
+     * ISO timestamp of the most recently modified file inside the project, or `null` for empty projects.
+     */
+    readonly latestModifiedAt: string | null;
+};
+
+/**
+ * Identification of the agent owning one projects folder.
+ */
+export type AgentProjectsOwner = {
+    /**
+     * Permanent id of the agent owning the projects.
+     */
+    readonly agentPermanentId: string;
+
+    /**
+     * Display name of the agent, or `null` when the agent row no longer exists in the database.
+     */
+    readonly agentName: string | null;
+
+    /**
+     * Local agent runner directory name, for example `agent-1dkmraaikkd8yp`.
+     */
+    readonly agentDirectoryName: string;
+
+    /**
+     * Numeric id of the server owning the agent, or `null` for the unregistered default server.
+     */
+    readonly serverId: number | null;
+
+    /**
+     * Display name of the server owning the agent, or `null` when the server is not registered.
+     */
+    readonly serverName: string | null;
+
+    /**
+     * Public domain of the server owning the agent, or `null` when the server is not registered.
+     */
+    readonly serverDomain: string | null;
+};
+
+/**
+ * All projects of one agent together with aggregated totals.
+ */
+export type AgentProjectsSummary = AgentProjectsOwner & {
+    /**
+     * Projects of the agent ordered by project name.
+     */
+    readonly projects: ReadonlyArray<AgentProjectInfo>;
+
+    /**
+     * Total size of all projects of the agent in bytes.
+     */
+    readonly totalSizeBytes: number;
+
+    /**
+     * Total count of files across all projects of the agent.
+     */
+    readonly totalFileCount: number;
+};
+
+/**
+ * Report of agent projects used by the per-server admin dashboard and the VPS resource monitor.
+ */
+export type AllAgentProjectsReport = {
+    /**
+     * Absolute path of the local agent root containing project folders.
+     */
+    readonly rootPath: string;
+
+    /**
+     * Count of agents checked for local project folders in the selected scope.
+     */
+    readonly totalAgentCount: number;
+
+    /**
+     * Per-agent project summaries for agents that have at least one project, ordered by total size descending.
+     */
+    readonly summaries: ReadonlyArray<AgentProjectsSummary>;
+
+    /**
+     * Total size of all projects of all agents in bytes.
+     */
+    readonly totalSizeBytes: number;
+
+    /**
+     * Total count of projects across all agents.
+     */
+    readonly totalProjectCount: number;
+
+    /**
+     * Total count of files across all projects of all agents.
+     */
+    readonly totalFileCount: number;
+
+    /**
+     * ISO timestamp when the report was generated.
+     */
+    readonly generatedAt: string;
+};

package/apps/agents-server/src/utils/agentProjects/AgentProjectReferenceInfo.ts

@@ -0,0 +1,19 @@
+import type { AgentProjectInfo } from './AgentProjectInfo';
+
+/**
+ * Browser-safe project metadata reused by project lists and chat references.
+ */
+export type AgentProjectReferenceInfo = Pick<
+    AgentProjectInfo,
+    'projectName' | 'displayName' | 'description' | 'sizeBytes'
+> & {
+    /**
+     * Whether the project currently accepts requests on its assigned runtime port.
+     */
+    readonly isRunning?: boolean;
+
+    /**
+     * Public runtime URL when the project has been assigned a runtime, otherwise `null`.
+     */
+    readonly projectUrl?: string | null;
+};

package/apps/agents-server/src/utils/agentProjects/AgentProjectRuntimeInfo.ts

@@ -0,0 +1,117 @@
+/**
+ * Modes supported by agent project runtimes.
+ */
+export const AGENT_PROJECT_RUNTIME_MODES = ['assigned-port', 'static-server', 'dev-server'] as const;
+
+/**
+ * Runtime mode of one agent project port.
+ */
+export type AgentProjectRuntimeMode = (typeof AGENT_PROJECT_RUNTIME_MODES)[number];
+
+/**
+ * Runtime statuses shown in project pages and the resource monitor.
+ */
+export const AGENT_PROJECT_RUNTIME_STATUSES = ['assigned', 'starting', 'running', 'stopped'] as const;
+
+/**
+ * Runtime status of one agent project port.
+ */
+export type AgentProjectRuntimeStatus = (typeof AGENT_PROJECT_RUNTIME_STATUSES)[number];
+
+/**
+ * Serializable metadata of one assigned or running project runtime.
+ */
+export type AgentProjectRuntimeInfo = {
+    /**
+     * Process-local id of the runtime record.
+     */
+    readonly id: string;
+
+    /**
+     * Permanent id of the agent owning the project.
+     */
+    readonly agentPermanentId: string;
+
+    /**
+     * Directory name of the project inside the agent `projects/` folder.
+     */
+    readonly projectName: string;
+
+    /**
+     * Absolute project directory path on the Agents Server disk.
+     */
+    readonly projectPath: string;
+
+    /**
+     * Runtime mode.
+     */
+    readonly mode: AgentProjectRuntimeMode;
+
+    /**
+     * Local TCP port assigned to the project.
+     */
+    readonly port: number;
+
+    /**
+     * Browser URL for the runtime.
+     *
+     * In production this is the public project domain. In local development it
+     * falls back to the loopback URL.
+     */
+    readonly url: string;
+
+    /**
+     * Local loopback URL assigned to the project runtime.
+     */
+    readonly localUrl: string;
+
+    /**
+     * Public browser URL assigned to the project runtime.
+     */
+    readonly publicUrl: string;
+
+    /**
+     * Public project domain, or `null` when no routable server domain is configured.
+     */
+    readonly domain: string | null;
+
+    /**
+     * Agents Server project page URL path.
+     */
+    readonly projectHref: string;
+
+    /**
+     * Shell command used for server-owned dev runtimes, or `null` for static/assigned ports.
+     */
+    readonly command: string | null;
+
+    /**
+     * Process id of the server-owned dev process, or `null` when no child process is owned.
+     */
+    readonly processId: number | null;
+
+    /**
+     * pm2 process name for server-owned runtimes, or `null` when the runtime is local-only.
+     */
+    readonly pm2ProcessName: string | null;
+
+    /**
+     * Current runtime status.
+     */
+    readonly status: AgentProjectRuntimeStatus;
+
+    /**
+     * Whether a TCP listener is currently available on the assigned port.
+     */
+    readonly isRunning: boolean;
+
+    /**
+     * ISO timestamp when this runtime was assigned.
+     */
+    readonly startedAt: string;
+
+    /**
+     * ISO timestamp of the latest status update.
+     */
+    readonly updatedAt: string;
+};

package/apps/agents-server/src/utils/agentProjects/agentProjectAccess.ts

@@ -0,0 +1,71 @@
+import {
+    resolveAgentAccess,
+    type AgentAccessResolution,
+    type ResolveAgentAccessOptions,
+} from '../agentAccess';
+
+/**
+ * Message returned when an anonymous user attempts to open project files or details.
+ */
+export const AGENT_PROJECT_DETAILS_FORBIDDEN_MESSAGE = 'Sign in to view project files and details.';
+
+/**
+ * Agent access enriched with project-specific permission flags.
+ */
+export type AgentProjectsAccessResolution = AgentAccessResolution & {
+    /**
+     * Whether the request belongs to a logged-in user.
+     */
+    readonly isAuthenticated: boolean;
+
+    /**
+     * Whether the request may see the project names and README files.
+     */
+    readonly isProjectOverviewVisible: boolean;
+
+    /**
+     * Whether the request may see project files, paths, sizes, and timestamps.
+     */
+    readonly isProjectDetailsVisible: boolean;
+};
+
+/**
+ * Returns whether project names and README files may be shown.
+ *
+ * @param agentAccess - General agent access decision.
+ * @returns `true` when the caller can see the limited projects overview.
+ */
+export function isAgentProjectsOverviewVisible(agentAccess: AgentAccessResolution): boolean {
+    return agentAccess.isAllowed;
+}
+
+/**
+ * Returns whether project files and metadata may be shown.
+ *
+ * @param agentAccess - General agent access decision.
+ * @returns `true` when the caller is logged in and may access the agent.
+ */
+export function isAgentProjectDetailsVisible(agentAccess: AgentAccessResolution): boolean {
+    return agentAccess.isAllowed && Boolean(agentAccess.currentUser);
+}
+
+/**
+ * Resolves agent access together with project-specific visibility decisions.
+ *
+ * @param agentIdentifier - Agent name, permanent id, or book-scoped child identifier.
+ * @param options - Request and internal TEAM access policy.
+ * @returns General agent access plus project-specific flags.
+ */
+export async function resolveAgentProjectsAccess(
+    agentIdentifier: string,
+    options: ResolveAgentAccessOptions = {},
+): Promise<AgentProjectsAccessResolution> {
+    const agentAccess = await resolveAgentAccess(agentIdentifier, options);
+
+    return {
+        ...agentAccess,
+        isAuthenticated: Boolean(agentAccess.currentUser),
+        isProjectOverviewVisible: isAgentProjectsOverviewVisible(agentAccess),
+        isProjectDetailsVisible: isAgentProjectDetailsVisible(agentAccess),
+    };
+}