@anhlp/alp-core 0.0.0-beta.1 → 0.0.0-beta.2

package/dist/init.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { projectProfiles, profileDefaults, syncTemplateProfiles } from "./profiles.js";
 import { validateSettings } from "./validation.js";
+import { INIT_TEAM } from "./workflow.js";
 async function initProject(projectRoot, { templateRoot, templates, library, syncProfiles = true, onlyManagedProfiles = false, teamIds } = {}) {
   const root = path.resolve(projectRoot);
   const sourceRoot = () => templateRoot ?? shippedTemplateRoot();
@@ -17,7 +18,7 @@ async function initProject(projectRoot, { templateRoot, templates, library, sync
   const team = await projectProfiles({ root, templates, library, teamIds });
   const files = {
     "ALP.md": await template("ALP.md"),
-    ".alp/settings.json": JSON.stringify({ defaultAgent: "main", workflow: { mode: "pho" }, team, templateDefaults: profileDefaults(team) }, null, 2) + "\n"
+    ".alp/settings.json": JSON.stringify({ defaultAgent: "main", workflow: { mode: INIT_TEAM }, team, templateDefaults: profileDefaults(team) }, null, 2) + "\n"
   };
   const directories = [".alp"];
   const created = [];

package/dist/teams.d.ts

@@ -3,20 +3,31 @@ export function validateTeam(config: any, source: any): any;
 /**
  * Where each team comes from: built in, then the library, then the project. A team
  * directory counts only with a team.json. `root` may be undefined outside a project.
+ * @param {string | undefined} root
+ * @param {{ library?: string, templates?: Record<string, string> }} [options]
  * @returns {Promise<Map<string, { source: 'builtin' | 'library' | 'project', directory?: string, overrides?: 'builtin' | 'library' }>>}
  */
-export function teamSources(root: any, { library, templates }?: {}): Promise<Map<string, {
+export function teamSources(root: string | undefined, { library, templates }?: {
+    library?: string;
+    templates?: Record<string, string>;
+}): Promise<Map<string, {
     source: "builtin" | "library" | "project";
     directory?: string;
     overrides?: "builtin" | "library";
 }>>;
 /**
  * A team by id, with its house rules.
+ * @param {string | undefined} root
+ * @param {string} id
+ * @param {{ library?: string, templates?: Record<string, string> }} [options]
  * @returns {Promise<{ id: string, source: 'builtin' | 'library' | 'project', label: string, description?: string, main: string,
  *   members: Record<string, { role?: string, model?: string, thinking?: string }>, delegation: Record<string, string[]>,
  *   oracleThinking?: Record<string, string>, oracleModels?: string[], maxPeers?: number, supervisor: false | { agent: string, model?: string, thinking?: string }, houseRules: string }>}
  */
-export function resolveTeam(root: any, id: any, { library, templates }?: {}): Promise<{
+export function resolveTeam(root: string | undefined, id: string, { library, templates }?: {
+    library?: string;
+    templates?: Record<string, string>;
+}): Promise<{
     id: string;
     source: "builtin" | "library" | "project";
     label: string;

package/dist/workflow.d.ts

@@ -1,14 +1,45 @@
 /**
- * The team a session runs in (ALPD §42): the one the caller selects, the one a resumed
- * session ran in, or settings' workflow.mode. Without any, the session is `custom`: its
- * graph is settings' delegation and no supervisor watches it.
+ * The team a session runs in when the caller selects none (ALPD §42, §60): the one a resumed
+ * session ran in, else settings' workflow.mode, else `custom` (settings' delegation graph, no
+ * supervisor). A project without .alp/settings.json gets init's settings when a session is
+ * created, so with `scaffolded` a missing file counts as naming INIT_TEAM. session.create and
+ * session.preview both resolve through here, so a preview names the team that would run.
+ * @param {Record<string, any>} settings the project's settings, `{}` when the file is missing
+ * @param {{ restored?: { mode: string }, scaffolded?: boolean }} [options]
+ */
+export function defaultTeam(settings: Record<string, any>, { restored, scaffolded }?: {
+    restored?: {
+        mode: string;
+    };
+    scaffolded?: boolean;
+}): any;
+/**
+ * The team a session runs in (ALPD §42): the one the caller selects, else defaultTeam. Without
+ * any, the session is `custom`: its graph is settings' delegation and no supervisor watches it.
+ * Selecting `custom` is refused unless it is the team that would run anyway, so a client may send
+ * back the team session.preview named.
+ * @param {string} root
+ * @param {string | undefined} selected
+ * @param {{ mode: string, maxPeers?: number, supervisor?: boolean } | undefined} restored
+ * @param {{ library?: string, templates?: Record<string, string>, scaffold?: boolean }} [options]
+ *   scaffold: a missing settings file will be written by init before the session runs (a preview).
  * @returns {Promise<{ mode: string, maxPeers: number, supervisor: boolean, team?: Awaited<ReturnType<typeof resolveTeam>> }>}
  */
-export function resolveWorkflow(root: any, selected: any, restored: any, { library, templates }?: {}): Promise<{
+export function resolveWorkflow(root: string, selected: string | undefined, restored: {
+    mode: string;
+    maxPeers?: number;
+    supervisor?: boolean;
+} | undefined, { library, templates, scaffold }?: {
+    library?: string;
+    templates?: Record<string, string>;
+    scaffold?: boolean;
+}): Promise<{
     mode: string;
     maxPeers: number;
     supervisor: boolean;
     team?: Awaited<ReturnType<typeof resolveTeam>>;
 }>;
 export { teamOf as profileOf } from "./teams.js";
+/** The team `alp init` names in a new project's settings (`init.js`). */
+export const INIT_TEAM: "pho";
 import { resolveTeam } from './teams.js';

package/dist/workflow.js

@@ -1,16 +1,23 @@
 // packages/core/src/workflow.js
 import path from "node:path";
-import { jsonObject } from "./resolver.js";
+import { jsonObject, optionalText } from "./resolver.js";
 import { applyProfile } from "./profiles.js";
 import { validateSettings } from "./validation.js";
 import { resolveTeam, teamOf } from "./teams.js";
 import { teamOf as teamOf2 } from "./teams.js";
-async function resolveWorkflow(root, selected, restored, { library, templates } = {}) {
-  const settings = await jsonObject(path.join(root, ".alp/settings.json"), "INVALID_SETTINGS");
+var INIT_TEAM = "pho";
+function defaultTeam(settings, { restored, scaffolded = false } = {}) {
+  return teamOf(restored?.mode ?? settings.workflow?.mode ?? (scaffolded ? INIT_TEAM : "custom"));
+}
+async function resolveWorkflow(root, selected, restored, { library, templates, scaffold = false } = {}) {
+  const file = path.join(root, ".alp/settings.json");
+  const settings = await jsonObject(file, "INVALID_SETTINGS");
   validateSettings(settings, ".alp/settings.json");
+  const scaffolded = scaffold && await optionalText(file) === void 0;
+  const fallback = defaultTeam(settings, { restored, scaffolded });
   const chosen = selected === void 0 ? void 0 : teamOf(selected);
-  if (chosen === "custom") throw new Error("Choose a team, such as pho (Ph\u1EDF) or cafe (Cafe)");
-  const mode = chosen ?? teamOf(restored?.mode ?? settings.workflow?.mode ?? "custom");
+  if (chosen === "custom" && fallback !== "custom") throw new Error("Choose a team, such as pho (Ph\u1EDF) or cafe (Cafe)");
+  const mode = chosen ?? fallback;
   if (restored && mode !== teamOf(restored.mode)) throw new Error("Cannot change team in an existing session");
   const team = mode === "custom" ? void 0 : applyProfile(await resolveTeam(root, mode, { library, templates }), (settings.team ?? settings.profile)?.[mode]);
   const maxPeers = restored?.maxPeers ?? settings.workflow?.maxPeers ?? team?.maxPeers ?? 2;
@@ -19,6 +26,8 @@ async function resolveWorkflow(root, selected, restored, { library, templates }
   return { mode, maxPeers, supervisor, ...team ? { team } : {} };
 }
 export {
+  INIT_TEAM,
+  defaultTeam,
   teamOf2 as profileOf,
   resolveWorkflow
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhlp/alp-core",
-  "version": "0.0.0-beta.1",
+  "version": "0.0.0-beta.2",
   "type": "module",
   "description": "ALP core module",
   "files": [
@@ -284,7 +284,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@anhlp/alp-protocol": "0.0.0-beta.1"
+    "@anhlp/alp-protocol": "0.0.0-beta.2"
   },
   "scripts": {
     "build": "node ../../scripts/build-workspace.mjs core",

package/src/init.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { projectProfiles, profileDefaults, syncTemplateProfiles } from './profiles.js';
 import { validateSettings } from './validation.js';
+import { INIT_TEAM } from './workflow.js';
 
 /**
  * Fill missing scaffold files without replacing existing user content: ALP.md and
@@ -24,7 +25,7 @@ export async function initProject(projectRoot, { templateRoot, templates, librar
   const team = await projectProfiles({ root, templates, library, teamIds });
   const files = {
     'ALP.md': await template('ALP.md'),
-    '.alp/settings.json': JSON.stringify({ defaultAgent: 'main', workflow: { mode: 'pho' }, team, templateDefaults: profileDefaults(team) }, null, 2) + '\n',
+    '.alp/settings.json': JSON.stringify({ defaultAgent: 'main', workflow: { mode: INIT_TEAM }, team, templateDefaults: profileDefaults(team) }, null, 2) + '\n',
   };
   const directories = ['.alp'];
   const created = [];

package/src/teams.js

@@ -100,6 +100,8 @@ async function directories(directory) {
 /**
  * Where each team comes from: built in, then the library, then the project. A team
  * directory counts only with a team.json. `root` may be undefined outside a project.
+ * @param {string | undefined} root
+ * @param {{ library?: string, templates?: Record<string, string> }} [options]
  * @returns {Promise<Map<string, { source: 'builtin' | 'library' | 'project', directory?: string, overrides?: 'builtin' | 'library' }>>}
  */
 export async function teamSources(root, { library, templates } = {}) {
@@ -120,6 +122,9 @@ export async function teamSources(root, { library, templates } = {}) {
 
 /**
  * A team by id, with its house rules.
+ * @param {string | undefined} root
+ * @param {string} id
+ * @param {{ library?: string, templates?: Record<string, string> }} [options]
  * @returns {Promise<{ id: string, source: 'builtin' | 'library' | 'project', label: string, description?: string, main: string,
  *   members: Record<string, { role?: string, model?: string, thinking?: string }>, delegation: Record<string, string[]>,
  *   oracleThinking?: Record<string, string>, oracleModels?: string[], maxPeers?: number, supervisor: false | { agent: string, model?: string, thinking?: string }, houseRules: string }>}

package/src/workflow.js

@@ -1,23 +1,48 @@
 import path from 'node:path';
-import { jsonObject } from './resolver.js';
+import { jsonObject, optionalText } from './resolver.js';
 import { applyProfile } from './profiles.js';
 import { validateSettings } from './validation.js';
 import { resolveTeam, teamOf } from './teams.js';
 
 export { teamOf as profileOf } from './teams.js';
 
+/** The team `alp init` names in a new project's settings (`init.js`). */
+export const INIT_TEAM = 'pho';
+
+/**
+ * The team a session runs in when the caller selects none (ALPD §42, §60): the one a resumed
+ * session ran in, else settings' workflow.mode, else `custom` (settings' delegation graph, no
+ * supervisor). A project without .alp/settings.json gets init's settings when a session is
+ * created, so with `scaffolded` a missing file counts as naming INIT_TEAM. session.create and
+ * session.preview both resolve through here, so a preview names the team that would run.
+ * @param {Record<string, any>} settings the project's settings, `{}` when the file is missing
+ * @param {{ restored?: { mode: string }, scaffolded?: boolean }} [options]
+ */
+export function defaultTeam(settings, { restored, scaffolded = false } = {}) {
+  return teamOf(restored?.mode ?? settings.workflow?.mode ?? (scaffolded ? INIT_TEAM : 'custom'));
+}
+
 /**
- * The team a session runs in (ALPD §42): the one the caller selects, the one a resumed
- * session ran in, or settings' workflow.mode. Without any, the session is `custom`: its
- * graph is settings' delegation and no supervisor watches it.
+ * The team a session runs in (ALPD §42): the one the caller selects, else defaultTeam. Without
+ * any, the session is `custom`: its graph is settings' delegation and no supervisor watches it.
+ * Selecting `custom` is refused unless it is the team that would run anyway, so a client may send
+ * back the team session.preview named.
+ * @param {string} root
+ * @param {string | undefined} selected
+ * @param {{ mode: string, maxPeers?: number, supervisor?: boolean } | undefined} restored
+ * @param {{ library?: string, templates?: Record<string, string>, scaffold?: boolean }} [options]
+ *   scaffold: a missing settings file will be written by init before the session runs (a preview).
  * @returns {Promise<{ mode: string, maxPeers: number, supervisor: boolean, team?: Awaited<ReturnType<typeof resolveTeam>> }>}
  */
-export async function resolveWorkflow(root, selected, restored, { library, templates } = {}) {
-  const settings = await jsonObject(path.join(root, '.alp/settings.json'), 'INVALID_SETTINGS');
+export async function resolveWorkflow(root, selected, restored, { library, templates, scaffold = false } = {}) {
+  const file = path.join(root, '.alp/settings.json');
+  const settings = await jsonObject(file, 'INVALID_SETTINGS');
   validateSettings(settings, '.alp/settings.json');
+  const scaffolded = scaffold && await optionalText(file) === undefined;
+  const fallback = defaultTeam(settings, { restored, scaffolded });
   const chosen = selected === undefined ? undefined : teamOf(selected);
-  if (chosen === 'custom') throw new Error('Choose a team, such as pho (Phở) or cafe (Cafe)');
-  const mode = chosen ?? teamOf(restored?.mode ?? settings.workflow?.mode ?? 'custom');
+  if (chosen === 'custom' && fallback !== 'custom') throw new Error('Choose a team, such as pho (Phở) or cafe (Cafe)');
+  const mode = chosen ?? fallback;
   if (restored && mode !== teamOf(restored.mode)) throw new Error('Cannot change team in an existing session');
   const team = mode === 'custom' ? undefined : applyProfile(await resolveTeam(root, mode, { library, templates }), (settings.team ?? settings.profile)?.[mode]);
   const maxPeers = restored?.maxPeers ?? settings.workflow?.maxPeers ?? team?.maxPeers ?? 2;