agent-apprenticeship 0.1.9 → 0.2.0

package/bin/agent-apprenticeship.js

@@ -115,6 +115,66 @@ function setupHeartbeatMs(defaultMs) {
   return Number.isFinite(value) && value > 0 ? value : defaultMs;
 }
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function acquireRuntimeLock(lockPath) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  const started = Date.now();
+  let lastHeartbeat = 0;
+  const staleMs = setupTimeout(15 * 60 * 1000);
+  const waitMs = setupTimeout(15 * 60 * 1000);
+  while (true) {
+    try {
+      const fd = fs.openSync(lockPath, "wx");
+      fs.writeFileSync(fd, JSON.stringify({
+        pid: process.pid,
+        createdAt: new Date().toISOString()
+      }, null, 2) + "\n");
+      return () => {
+        try {
+          fs.closeSync(fd);
+        } catch (_) {
+          // Best effort cleanup.
+        }
+        try {
+          fs.unlinkSync(lockPath);
+        } catch (_) {
+          // Best effort cleanup.
+        }
+      };
+    } catch (error) {
+      if (!error || error.code !== "EEXIST") throw error;
+      let stale = false;
+      try {
+        const stat = fs.statSync(lockPath);
+        stale = Date.now() - stat.mtimeMs > staleMs;
+      } catch (_) {
+        stale = true;
+      }
+      if (stale) {
+        try {
+          fs.unlinkSync(lockPath);
+        } catch (_) {
+          // Another process may have refreshed or removed the lock.
+        }
+        continue;
+      }
+      if (Date.now() - started > waitMs) {
+        console.error("Timed out waiting for another Agent Apprenticeship runtime setup to finish.");
+        console.error(`Lock file: ${lockPath}`);
+        process.exit(1);
+      }
+      if (Date.now() - lastHeartbeat > setupHeartbeatMs(30000)) {
+        console.error("Waiting for another Agent Apprenticeship runtime setup to finish...");
+        lastHeartbeat = Date.now();
+      }
+      await sleep(1000);
+    }
+  }
+}
+
 function runQuiet(command, args, label, timeoutMs) {
   return new Promise((resolve) => {
     let stdout = "";
@@ -193,28 +253,42 @@ async function ensureRuntime(python) {
     // Fall through and rebuild the runtime.
   }
 
-  console.error("Installing Agent Apprenticeship runtime...");
-  console.error("First run can take a few minutes while Python dependencies are installed.");
-  fs.rmSync(venvDir, { recursive: true, force: true });
-  fs.mkdirSync(path.dirname(venvDir), { recursive: true });
-  await runQuiet(python, ["-m", "venv", venvDir], "create the Python environment", 120000);
-  await runQuiet(py, [
-    "-m", "pip", "install",
-    "--disable-pip-version-check",
-    "--progress-bar", "off",
-    "--no-input",
-    "--no-build-isolation",
-    "--retries", "10",
-    "--timeout", "60",
-    packageRoot
-  ], "install the Python package", 600000);
-  fs.writeFileSync(markerPath, JSON.stringify({
-    packageName: packageJson.name,
-    packageVersion: packageJson.version,
-    installedAt: new Date().toISOString()
-  }, null, 2) + "\n");
-  console.error("Done.");
-  return py;
+  const releaseLock = await acquireRuntimeLock(`${venvDir}.install.lock`);
+  try {
+    try {
+      const marker = JSON.parse(fs.readFileSync(markerPath, "utf8"));
+      if (marker.packageVersion === packageJson.version && fs.existsSync(py)) {
+        return py;
+      }
+    } catch (_) {
+      // This process owns the setup lock and will rebuild the runtime.
+    }
+
+    console.error("Installing Agent Apprenticeship runtime...");
+    console.error("First run can take a few minutes while Python dependencies are installed.");
+    fs.rmSync(venvDir, { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(venvDir), { recursive: true });
+    await runQuiet(python, ["-m", "venv", venvDir], "create the Python environment", 120000);
+    await runQuiet(py, [
+      "-m", "pip", "install",
+      "--disable-pip-version-check",
+      "--progress-bar", "off",
+      "--no-input",
+      "--no-build-isolation",
+      "--retries", "10",
+      "--timeout", "60",
+      packageRoot
+    ], "install the Python package", 600000);
+    fs.writeFileSync(markerPath, JSON.stringify({
+      packageName: packageJson.name,
+      packageVersion: packageJson.version,
+      installedAt: new Date().toISOString()
+    }, null, 2) + "\n");
+    console.error("Done.");
+    return py;
+  } finally {
+    releaseLock();
+  }
 }
 
 function runCli(python, args, usePackagedSource) {

package/docs/bioactive_evidence_mapping_schema.md

@@ -0,0 +1,113 @@
+# Bioactive Evidence Mapping Extension Schema
+
+This optional Agent Apprenticeship schema describes evidence-mapping rows for specialized research and decision-support datasets. It is a general Experience Compilation extension and does not change the core product into a wellness-only tool.
+
+These rows are for provenance, uncertainty tracking, citation grounding, mechanism mapping, and verifier training. They are not medical advice, diagnosis, treatment guidance, cure claims, or sensitive personal records.
+
+## Row Families
+
+### evidence_mapping_sft_rows
+
+LoRA-ready instruction-tuning view for extracting grounded ingredient, compound, product, evidence, mechanism, safety/caution, and uncertainty fields from provided local source material.
+
+Required fields:
+
+- `row_id`
+- `schema_version`
+- `data_type`
+- `source_task_id`
+- `domain`
+- `subdomain`
+- `workflow_family`
+- `instruction`
+- `input_context`
+- `target_output`
+- `source_text_or_artifact_ref`
+- `source_evidence_ref_ids`
+- `quality_score`
+- `confidence`
+
+### ingredient_claim_verifier_rows
+
+Verifier-training view for checking whether a claim is supported by visible source evidence.
+
+Required fields:
+
+- `row_id`
+- `claim`
+- `ingredient_or_compound_entity`
+- `visible_evidence`
+- `expected_contract`
+- `verifier_decision`
+- `failure_reason`
+- `confidence`
+- `source_evidence_ref_ids`
+
+### product_ingredient_extraction_rows
+
+Extraction view for mapping product labels or specification tables into structured ingredient/product entities.
+
+Required fields:
+
+- `row_id`
+- `product_entity`
+- `ingredient_or_compound_entities`
+- `source_text_or_artifact_ref`
+- `extraction_contract`
+- `citation_or_provenance_refs`
+- `source_evidence_ref_ids`
+- `confidence`
+
+### mechanism_mapping_rows
+
+Mechanism evidence view for mapping a claim or source passage into a mechanism category with uncertainty.
+
+Required fields:
+
+- `row_id`
+- `ingredient_or_compound_entity`
+- `mechanism_category`
+- `evidence_summary`
+- `uncertainty`
+- `citation_or_provenance_refs`
+- `source_evidence_ref_ids`
+- `confidence`
+
+### safety_caution_rows
+
+Safety/caution evidence view for neutral flags and context constraints. Use abstract personal-context constraints only, never sensitive identity data.
+
+Required fields:
+
+- `row_id`
+- `ingredient_or_compound_entity`
+- `safety_caution_category`
+- `personal_context_constraints`
+- `evidence_summary`
+- `uncertainty`
+- `citation_or_provenance_refs`
+- `source_evidence_ref_ids`
+- `confidence`
+
+### citation_grounding_rows
+
+Grounding view for checking whether generated summaries cite visible evidence correctly.
+
+Required fields:
+
+- `row_id`
+- `generated_claim_or_summary`
+- `citation_or_provenance_refs`
+- `visible_evidence`
+- `verifier_decision`
+- `failure_reason`
+- `source_evidence_ref_ids`
+- `confidence`
+
+## Safety Rules
+
+- Use only provided local source material or package evidence refs.
+- Keep personal context as abstract constraints such as `pregnancy_context`, `medication_interaction_context`, or `allergy_context`; do not store identity or sensitive user details.
+- Record uncertainty and provenance for every extracted claim.
+- Do not infer treatment, cure, diagnosis, or patient-specific recommendations.
+- Do not mark unsupported claims as accepted verifier rows.

package/docs/dataset_schema.md

@@ -0,0 +1,160 @@
+# Agent Apprenticeship Dataset And Package Schema
+
+Agent Apprenticeship packages capture real agent workflows as reusable experience. A package may include task packets, Apprentice-generated task specs, audited rubrics, traces, actual outputs, artifacts, evaluator/verifier/grader records, mentor or expert checkpoint records, follow-ups, Experience Compiler outputs, and public ecosystem storage references.
+
+## Apprenticeship Modes
+
+New package metadata uses:
+
+- `apprenticeship_mode = autonomous`
+- `apprenticeship_mode = expert_led`
+- `apprenticeship_mode = org_custom`
+
+Legacy packages may include `mentor_mode` for internal compatibility. New public indexes, R2 ecosystem items, compiler manifests, and contribution manifests should include `apprenticeship_mode`.
+
+## Agent Training Contribution Mode
+
+Local settings support:
+
+- Public Ecosystem: completed Experience Compilations are shared through the Forsy R2 ecosystem backend by default.
+- Private Internal Only: completed packages remain local.
+
+This setting is local user preference. It is not written as a public ecosystem item field.
+
+## Core Package Layout
+
+Typical local package content:
+
+- `task/` for task packet, task brief, inputs, and task-intake spec
+- `rubric/` for Apprentice-generated rubric plus audit metadata
+- `attempts/<kind>/agent_trace.json`
+- `attempts/<kind>/actual_outputs.json`
+- `attempts/<kind>/artifacts/`
+- `grading/`, `feedback/`, and `signals/`
+- `mentor_checkpoints/` when expert or organization workflows record checkpoints
+- `experience_compiler/`
+- optional legacy `tdo/` compatibility outputs
+
+`actual_outputs.json` remains the canonical output contract. Final/static outputs are represented by actual outputs, deliverable refs, artifact refs, and copied files rather than large top-level trace fields.
+
+## Experience Compiler Outputs
+
+The Experience Compiler turns completed workflows into reusable skills, evals, verifier specs, reward signals, environment-response rows, runtime learning packages, and training-ready datasets.
+
+Public compiler layout:
+
+- `experience_compiler/compiler_manifest.json`
+- `experience_compiler/compiler_report.json`
+- `experience_compiler/compiler_trace.jsonl`
+- `experience_compiler/compiler_rounds.jsonl`
+- `experience_compiler/compiler_recipe.json`
+- `experience_compiler/compiler_judge_results.jsonl`
+- `experience_compiler/learning_objects_index.json`
+- `experience_compiler/experience_pack/`
+- `experience_compiler/skill_pack/skill.md`
+- `experience_compiler/runtime_learning_package/`
+- `experience_compiler/training_time_package/`
+- `experience_compiler/evals/`
+- `experience_compiler/verifier/`
+- `experience_compiler/reward/`
+- `experience_compiler/environment/`
+- `experience_compiler/reports/`
+
+`skill_pack/skill.md` should be task-specific and evidence-grounded, with best-use guidance, prerequisites, workflow steps, decision points, common failure patterns, recovery strategies, evidence and artifact expectations, verification checklist, examples, and transfer notes.
+
+## Loop Review Evidence
+
+Current Experience Compilations may include per-iteration loop evidence under `loops/`. These artifacts make autonomous model-review loops and Expert-Led review loops inspectable before feedback or continuation decisions.
+
+Required loop review artifacts, when a loop iteration runs:
+
+- `loops/loop_manifest.json`
+- `loops/iterations/<nnn>/review_packet.json`
+- `loops/iterations/<nnn>/review_packet.md`
+- `loops/iterations/<nnn>/output_snapshot.json`
+- `loops/iterations/<nnn>/artifact_index.json`
+- `loops/iterations/<nnn>/trace_refs.json`
+- `loops/iterations/<nnn>/rubric_status.json`
+- `loops/iterations/<nnn>/verifier_status.json`
+- `loops/iterations/<nnn>/evaluator_feedback.json`
+- `loops/iterations/<nnn>/reviewer_feedback.json`
+- `loops/iterations/<nnn>/revision_plan.json`
+- `loops/iterations/<nnn>/diff_report.json`
+- `loops/iterations/<nnn>/loop_decision.json`
+
+Review packets should summarize the current goal, current outputs, actual output contract, artifacts, trace refs, key trace evidence, rubric/verifier status, known failures, missing outputs, surface and environment summaries, diffs, review instructions, and stop/continue choices. `reviewer_feedback.json` should record whether feedback came from a Mentor Model Provider, human expert, organization/custom reviewer, or simulated test checkpoint. Simulated feedback must be labelled as simulated.
+
+Experience Compiler evidence maps can reference `review_packet.json`, `reviewer_feedback.json`, `revision_plan.json`, `loop_decision.json`, and `diff_report.json`. Loop evidence can support critique/revision pairs, reward-model rows, verifier rows, process-supervision rows, failure modes, recovery strategies, and runtime decision rules. Older seed packages remain valid when loop review evidence is absent.
+
+## Runtime Learning Package
+
+Runtime learning material can be injected into future local runs as reusable experience. It may include runtime memory rows, tool-use hints, correction patterns, and Experience Pack references. It must not claim model weights were updated.
+
+## Ecosystem Learning And Experience Packs
+
+Ecosystem Learning creates reversible Experience Packs from seed tasks, Experience Compilations, or pulled ecosystem items. Each Experience Pack contains `skill.md`, compact source refs, replay results, status records, and activation metadata.
+
+## Training-Time Package
+
+Training-time material is ready for future supervised fine-tuning, eval building, verifier training, reward modeling, preference optimization, and environment-response training. It may include:
+
+- `training_examples.jsonl`
+- `evaluation_examples.jsonl`
+- `verifier_examples.jsonl`
+- `reward_model_rows.jsonl`
+- `preference_pairs.jsonl`
+- `failure_cases.jsonl`
+- `task_variants.jsonl`
+- `transfer_eval_tasks.jsonl`
+
+Rows should preserve `source_package_id`, `source_task_id`, `source_trace_id`, `source_step_ids`, `source_artifact_refs`, `source_evaluation_refs`, provenance, quality/fidelity/difficulty/learnability/reuse scores, judge source, audit status, and acceptance status.
+
+## Environment And Surface Data
+
+The environment folder can include:
+
+- `environment_spec.json`
+- `environment_response_pairs.jsonl`
+- `multi_agent_handoffs.jsonl`
+- `multimodal_artifacts.jsonl`
+- `ui_interaction_events.jsonl`
+- `physical_environment_events.jsonl`
+- `api_interaction_events.jsonl`
+- `mcp_interaction_events.jsonl`
+- `database_events.jsonl`
+- `structured_table_events.jsonl`
+- `software_execution_events.jsonl`
+- `search_retrieval_events.jsonl`
+- `enterprise_app_events.jsonl`
+- `async_workflow_events.jsonl`
+- `collaboration_events.jsonl`
+- `document_events.jsonl`
+- `cross_system_events.jsonl`
+
+Empty optional files are valid when a surface is absent.
+
+## Environment Spec
+
+`environment_spec.json` describes replay and world-model readiness. It may include environment type/domain, interaction surfaces, tools, runtime dependencies, input artifacts, setup commands, initial-state refs, allowed actions, reset strategy, verification commands, scoring refs, expected outputs, replay smoke-test details, and sections for API, MCP, database, spreadsheet, software execution, async workflows, collaboration, documents, cross-system dependencies, multi-agent, multimodal, UI/software, and physical/industrial workflows.
+
+## Evaluation Authority
+
+Goal achievement and outcome quality belong to mentor, expert, evaluator, verifier, and grader records. Apprentice Agent self-assessment is not the source of truth. Structural guardrails may check schemas, paths, refs, secrets, and package completeness, but they are not semantic judges.
+
+## R2 Public Ecosystem Records
+
+R2 ecosystem index records include item id, kind, title, summary, domain, subdomain, tags, timestamps, source, package id, task id, `apprenticeship_mode`, Apprentice Agent, Mentor Model Provider, status, counts, Experience Compiler row counts, contributor pseudonymous user id, and storage refs.
+
+Records do not include Agent Training Contribution Mode, local OS username, local hostname, secrets, Cloudflare credentials, or private local paths.
+
+## Backward Compatibility
+
+Raw seed traces and older local packages remain compatible even if new fields are missing. Normalizers should preserve new fields when present and tolerate missing optional fields in older traces. Derived/enriched outputs can be added later without mutating the original seed dataset.
+
+## Future Central Dataset Readiness
+
+Future enrichment can build environment specs, environment-response rows, training examples, eval examples, verifier examples, reward rows, preference pairs, failure cases, task variants, compiler reports, and meta-optimization records across the full seed dataset. This should be versioned clearly and uploaded through central infrastructure, not by mutating local seed data by default.
+
+## Exclusions
+
+Dataset and public package metadata must not include commerce metadata, public ranking language, Apprentice Agent self-eval as outcome truth, API keys, auth tokens, cookies, `.env`, `.env.local`, private local paths, source scrape internals, or huge embedded binaries.

package/docs/local_usage.md

@@ -0,0 +1,191 @@
+# Local Usage
+
+Initialize Agent Apprenticeship:
+
+```bash
+apprentice init --setup
+```
+
+`apprentice` is the short command used in normal docs. `agent-apprenticeship` remains available as the long-form compatibility command.
+
+Run a task:
+
+```bash
+apprentice run "Analyze this CSV and produce an executive summary" --asset ./data.csv
+```
+
+Start interactively:
+
+```bash
+apprentice start
+```
+
+Continue or finish a run:
+
+```bash
+apprentice continue <run_id> "Add sensitivity analysis" --asset ./updated_assumptions.csv
+apprentice finish <run_id>
+```
+
+Each run is written under `~/.agent-apprenticeship/runs/<run-id>/` with progress files, task outputs, traces, Experience Compiler outputs, and an Experience Compilation.
+
+```text
+run_status.json
+progress_events.jsonl
+actual_outputs.json
+experience_compiler/
+contribution_bundle/
+```
+
+Check or watch progress:
+
+```bash
+apprentice status <run_id>
+apprentice watch <run_id>
+```
+
+Use output modes when scripting:
+
+```bash
+apprentice run "Prepare a market brief" --quiet
+apprentice run "Prepare a market brief" --verbose
+apprentice run "Prepare a market brief" --json-progress
+```
+
+## Configuration
+
+Configure the Apprentice Agent, Mentor Model Provider, Apprenticeship Mode, and Agent Training Contribution Mode:
+
+```bash
+apprentice configure agent
+apprentice configure model
+apprentice configure apprenticeship
+apprentice configure contribution
+apprentice settings
+apprentice doctor
+```
+
+Apprenticeship Modes:
+
+- `autonomous`: Autonomous Apprenticeship. The agent works through the task with model guidance, iterative improvement loops, evaluation, and Experience Compiler outputs.
+- `expert-led`: Expert-Led Apprenticeship. The agent works with human expert checkpoints until acceptance criteria are met, expert sign-off is recorded, or the configured loop limit is reached.
+- `org-custom`: Organization Custom. For teams that need private deployment, custom integrations, internal storage, workflow-specific capture, or forward-deployed setup.
+
+Autonomous Apprenticeship needs a ready Mentor Model Provider. API keys are read from exported environment variables first and then from `.env.local` in the project or app home. `.env.local` is gitignored and key values are never printed.
+
+Agent Training Contribution Modes:
+
+- `public-ecosystem`: completed task and follow-up packages are shared to the Forsy ecosystem through Cloudflare R2.
+- `private-internal-only`: packages stay local unless explicitly contributed later.
+
+```bash
+apprentice ecosystem configure --training-contribution public-ecosystem
+apprentice ecosystem configure --training-contribution private-internal-only
+```
+
+## Integrations
+
+Apprentice Agents:
+
+- `codex`
+- `cursor`
+- `claude-code`
+- `openclaw`
+- `opencode`
+- `hermes-agent`
+- `custom`
+
+Mentor Model Providers:
+
+- `openai`
+- `anthropic`
+- `google`
+- `openrouter`
+
+Run:
+
+```bash
+apprentice integrations
+apprentice certify-integrations --all
+```
+
+Use `--all-combinations` only when you intentionally want every Apprentice Agent and Mentor Model Provider pair; it is slower and can consume provider quota.
+
+## Experience Compiler
+
+The Experience Compiler turns each completed workflow into reusable skills, evals, verifier specs, reward signals, environment-response data, runtime learning packages, and training-ready datasets.
+
+Public packages include:
+
+```text
+experience_compiler/
+  experience_pack/
+  skill_pack/
+  runtime_learning_package/
+  training_time_package/
+  evals/
+  verifier/
+  reward/
+  environment/
+  reports/
+```
+
+`actual_outputs.json` remains the canonical output contract for completed task artifacts.
+
+## Ecosystem
+
+Cloudflare R2 is the default ecosystem storage backend.
+
+```bash
+apprentice ecosystem status
+apprentice ecosystem list
+apprentice ecosystem search "finance"
+apprentice ecosystem inspect <item_id>
+apprentice ecosystem pull <item_id>
+```
+
+Share a package explicitly:
+
+```bash
+apprentice ecosystem contribute ~/.agent-apprenticeship/runs/<run-id>/contribution_bundle
+```
+
+Dry-run a share:
+
+```bash
+apprentice ecosystem contribute ~/.agent-apprenticeship/runs/<run-id>/contribution_bundle --dry-run
+```
+
+Legacy GitHub issue submission remains available only when explicitly selected:
+
+```bash
+apprentice ecosystem contribute <bundle_path> --storage github
+```
+
+Inspect local sharing history:
+
+```bash
+apprentice ecosystem identity
+apprentice ecosystem shared
+apprentice ecosystem shared --json
+apprentice ecosystem list --mine
+```
+
+## Ecosystem Learning
+
+Use Ecosystem Learning when you want your Apprentice Agent to learn from an ecosystem task, trace, or package through a reversible Experience Pack.
+
+```bash
+apprentice ecosystem search cloud
+apprentice ecosystem pull aa-seed-task-501
+apprentice learn create aa-seed-task-501
+apprentice learn preview <pack_id>
+apprentice learn replay <pack_id>
+apprentice learn keep <pack_id>
+apprentice run "Create a related incident response checklist" --experience-pack <pack_id>
+apprentice learn revert <pack_id>
+```
+
+Experience Packs live in `~/.agent-apprenticeship/experience_packs/<pack_id>/`.
+
+Rich artifacts are included through indexing rather than special folder rules. Reports, spreadsheets, CSV/JSON/Markdown, screenshots, browser logs, MCP/tool logs, notebooks, code, and generated files are packaged when they appear in the run/package artifact areas and are linked to trace steps.

package/docs/scaling_to_1000_tasks.md

@@ -0,0 +1,3 @@
+# Scaling to 1000 tasks
+
+Use `run-batch` with checkpointing, resume, progress logging, local packages, and release export. Start with 1, then 3, then 10 tasks before increasing parallelism. Each task packet preserves workflow traces, artifacts, model-judged evaluation, verifier-backed reliability, and revision signals for downstream research use.