agent-apprenticeship 0.1.1 → 0.1.2

package/README.md

@@ -1,25 +1,16 @@
 # Agent Apprenticeship
 
-The living ecosystem where AI agents learn from real-world work through iterative loops, reusable experience, and training-signal exchange.
+The living ecosystem where AI agents learn from real-world work through iterative workflow loops, reusable experience, and collective training signal exchange.
 
-As agents move into long-horizon, economically valuable work, Agent Apprenticeship creates the open infrastructure where useful work generates reusable learning signals and challenging tasks improve through automated iterative loops.
+As agents move into long-horizon, economically valuable work, Agent Apprenticeship creates the open infrastructure where real-world tasks generate reusable learning signals and complex workflows advance through agent loops that turn execution into shared improvement.
 
-Agent Apprenticeship is designed for an infinite exchange of work experience between agents: useful work creates training signals, signals improve future work, and future work creates new signals for the ecosystem.
+Agent Apprenticeship is designed for a compounding exchange of agent work experience: economically valuable task execution generates training signals, those signals improve future work, and future work creates new reusable experience for the ecosystem.
 
-Agent Apprenticeship is built for loop iterations across domains, from simple tasks to complex specialized workflows. Apprentice agents can work with mentor agents to accomplish long-horizon, real-world tasks across model-assisted, expert-led, and hybrid modes, generating learning signals throughout the process.
+Agent Apprenticeship is built for iterative workflow loops across domains, from simple tasks to complex specialized work. Apprentice agents work with mentor agents or human experts to complete long-horizon, real-world tasks, while each workflow generates reusable learning signals for the ecosystem.
 
-The first seed dataset includes:
+Agent Apprenticeship is now available for anyone to start using with local agents including Codex, Cursor, Claude Code, OpenClaw, OpenCode, Hermes Agent, and custom agents, alongside different model providers. Users can run automated agent workflow loops locally, contribute agent learning signals back to the ecosystem, and use shared ecosystem signals to improve their own agents.
 
-* 500+ curated seed tasks sourced and grounded from real world
-* 495 reusable agent lessons
-* 1000+ full agent execution traces
-* 1000+ agent work episodes / task rollouts
-
-The seed dataset spans specialized economically valuable tasks across domains and forms the first layer of the Agent Apprenticeship ecosystem.
-
-Agent Apprenticeship is now available for anyone to start using with local agents including Codex, Cursor, Claude Code, OpenClaw, OpenCode, Hermes Agent, and custom agents, alongside different model providers. Users can experience automated iterative loops locally, contribute agent learning signals back to the ecosystem, and access ecosystem learning signals to improve their own agents.
-
-Agent Apprenticeship is also about the future of work and the economic value of agents. For every task executed through Agent Apprenticeship, the system can estimate task-level economic value, especially across specialized domains. It is built for everyday use to improve agent performance and outcome quality, while also enabling users to exchange agent work experience with each other and with domain-expert-led agents in one living ecosystem.
+Agent Apprenticeship is about the future of work and the economic value of agents. For every task executed through Agent Apprenticeship, the system can estimate task-level economic value, especially across specialized domains. It is built for everyday use to improve agent performance and outcome quality, while enabling users to exchange agent work experience with each other and with domain-expert-led agents in one living ecosystem.
 
 ## Install
 

package/bin/agent-apprenticeship.js

@@ -64,15 +64,15 @@ function findPython() {
     process.exit(1);
   }
   const candidates = [
-    "python3.13",
-    "python3.12",
     "python3.11",
-    "/opt/homebrew/bin/python3.13",
-    "/opt/homebrew/bin/python3.12",
+    "python3.12",
+    "python3.13",
     "/opt/homebrew/bin/python3.11",
-    "/usr/local/bin/python3.13",
-    "/usr/local/bin/python3.12",
+    "/opt/homebrew/bin/python3.12",
+    "/opt/homebrew/bin/python3.13",
     "/usr/local/bin/python3.11",
+    "/usr/local/bin/python3.12",
+    "/usr/local/bin/python3.13",
     "python3",
     "python"
   ];
@@ -88,17 +88,51 @@ function venvPython(venvDir) {
     : path.join(venvDir, "bin", "python");
 }
 
-function runQuiet(command, args, label) {
+function runtimeEnv() {
+  const env = { ...process.env };
+  if (!env.PIP_CACHE_DIR) {
+    env.PIP_CACHE_DIR = path.join(appHome(), "pip-cache");
+  }
+  return env;
+}
+
+function setupTimeout(defaultMs) {
+  const raw = process.env.AA_NPM_SETUP_TIMEOUT_MS;
+  if (!raw) return defaultMs;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : defaultMs;
+}
+
+function runQuiet(command, args, label, timeoutMs) {
   const result = spawnSync(command, args, {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
-    env: process.env
+    env: runtimeEnv(),
+    timeout: setupTimeout(timeoutMs)
   });
   if (result.error || result.status !== 0) {
     console.error(`Agent Apprenticeship runtime setup failed while trying to ${label}.`);
-    if (result.error) console.error(String(result.error.message || result.error));
+    const timedOut = Boolean(result.signal) || (result.error && String(result.error.message || result.error).includes("ETIMEDOUT"));
+    if (timedOut) {
+      console.error("Runtime setup timed out. Re-run the command, or set AA_PYTHON to a working Python 3.11+ interpreter.");
+    } else if (result.error) {
+      const message = String(result.error.message || result.error);
+      console.error(message);
+    }
     const out = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
-    if (out) console.error(out);
+    if (out) console.error(out.slice(-4000));
+    process.exit(result.status || 1);
+  }
+}
+
+function runVisible(command, args, label) {
+  const result = spawnSync(command, args, {
+    stdio: "inherit",
+    env: runtimeEnv()
+  });
+  if (result.error || result.status !== 0) {
+    console.error(`Agent Apprenticeship runtime setup failed while trying to ${label}.`);
+    if (result.error) console.error(String(result.error.message || result.error));
     process.exit(result.status || 1);
   }
 }
@@ -117,10 +151,20 @@ function ensureRuntime(python) {
   }
 
   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 });
-  runQuiet(python, ["-m", "venv", venvDir], "create the Python environment");
-  runQuiet(py, ["-m", "pip", "install", "--disable-pip-version-check", "--no-input", "--quiet", packageRoot], "install the Python package");
+  runQuiet(python, ["-m", "venv", venvDir], "create the Python environment", 120000);
+  runQuiet(py, [
+    "-m", "pip", "install",
+    "-q",
+    "--disable-pip-version-check",
+    "--progress-bar", "off",
+    "--no-input",
+    "--retries", "10",
+    "--timeout", "60",
+    packageRoot
+  ], "install the Python package", 600000);
   fs.writeFileSync(markerPath, JSON.stringify({
     packageName: packageJson.name,
     packageVersion: packageJson.version,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-apprenticeship",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The living ecosystem for AI agents learning from real-world work through iterative loops and training-signal exchange.",
   "license": "MIT",
   "repository": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-apprenticeship"
-version = "0.1.1"
+version = "0.1.2"
 description = "Open framework for turning real agent work into transferable agent experience"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/agent_apprenticeship_trace/__init__.py

@@ -1,2 +1,2 @@
 """Agent Apprenticeship framework."""
-__version__ = "0.1.1"
+__version__ = "0.1.2"

package/src/agent_apprenticeship_trace/apprentice_adapters.py

@@ -14,6 +14,7 @@ from .codex_runner import (
     _attempt_dir,
     _copy_attempt_inputs,
     _deliverables,
+    _run_with_process_group_timeout,
     ensure_attempt_outputs,
 )
 from .config import get_settings
@@ -271,7 +272,7 @@ def run_external_agent_attempt(package_root: Path, raw: RawTaskRecord, spec: Tas
             run_error = RuntimeError(invocation.unsupported_reason)
         else:
             try:
-                cp = subprocess.run(invocation.argv, cwd=d, text=True, capture_output=True, timeout=timeout or settings.task_timeout_seconds)
+                cp = _run_with_process_group_timeout(invocation.argv, cwd=d, timeout=timeout or settings.task_timeout_seconds)
                 returncode = cp.returncode
                 stdout = cp.stdout or ""
                 stderr = cp.stderr or ""

package/src/agent_apprenticeship_trace/bundle_exporter.py

@@ -8,7 +8,7 @@ from typing import Any
 
 from .config import Settings, get_settings, normalize_mentor_mode
 from .io import append_jsonl, read_json, read_jsonl, write_json
-from .public_sanitizer import sanitize_public_obj
+from .public_sanitizer import sanitize_public_obj, sanitize_public_text
 from .release_exporter import create_release
 
 
@@ -50,6 +50,30 @@ def _copy_json_if_exists(src: Path, dst: Path) -> bool:
     return True
 
 
+def _copy_public_file(src: Path, dst: Path) -> bool:
+    if not src.exists() or not src.is_file():
+        return False
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    if src.suffix == ".json":
+        try:
+            write_json(dst, _sanitize_bundle_json(read_json(src)))
+        except Exception:
+            dst.write_text(sanitize_public_text(src.read_text(errors="replace")) or "")
+    elif src.suffix == ".jsonl":
+        try:
+            dst.write_text("")
+            for row in read_jsonl(src):
+                append_jsonl(dst, sanitize_public_obj(row) if isinstance(row, dict) else row)
+        except Exception:
+            dst.write_text(sanitize_public_text(src.read_text(errors="replace")) or "")
+    else:
+        try:
+            dst.write_text(sanitize_public_text(src.read_text(errors="replace")) or "")
+        except UnicodeDecodeError:
+            shutil.copy2(src, dst)
+    return True
+
+
 def _run_status(release_root: Path) -> str:
     rows = read_jsonl(release_root / "packages_index.jsonl")
     statuses = [row.get("task_status") for row in rows if row.get("task_status")]
@@ -73,10 +97,10 @@ def contribution_counts(release_root: Path) -> dict[str, int]:
 def _write_card(bundle_root: Path) -> None:
     (bundle_root / "contribution_card.md").write_text(
         "# Agent Apprenticeship Contribution Bundle\n\n"
-        "This local bundle packages an apprenticeship session for review and later contribution. "
+        "This local bundle packages an apprenticeship session for public ecosystem contribution. "
         "It includes session events, task instructions, traces, actual outputs, evaluation results, "
         "and learning-data views when available.\n\n"
-        "No automatic upload is performed. Review this folder locally before sharing.\n\n"
+        "No automatic upload is performed. Inspect this folder locally before sharing.\n\n"
         "To contribute, submit the bundle to the Agent Apprenticeship ecosystem repo, "
         "or get help in Slack: https://join.slack.com/t/fsycommunity/shared_invite/zt-37417grrb-jFD6BQIYgC5wEMrW2bHssw\n"
     )
@@ -128,6 +152,7 @@ def _copy_clean_bundle_files(release_root: Path, bundle_root: Path, include_debu
 
     _copy_jsonl_if_nonempty(release_root / "actual_outputs.jsonl", bundle_root / "outputs" / "actual_outputs.jsonl")
     _copy_json_if_exists(release_root / "artifacts_index.json", bundle_root / "outputs" / "artifacts_index.json")
+    _copy_indexed_package_files(release_root, bundle_root)
 
     for name in [
         "grader_results.jsonl",
@@ -159,6 +184,41 @@ def _copy_clean_bundle_files(release_root: Path, bundle_root: Path, include_debu
             shutil.rmtree(bundle_root / "debug")
 
 
+def _copy_indexed_package_files(release_root: Path, bundle_root: Path) -> None:
+    index_path = release_root / "artifacts_index.json"
+    if not index_path.exists():
+        return
+    raw_rows = read_json(index_path)
+    if not isinstance(raw_rows, list):
+        return
+    task_ids = sorted({str(row.get("task_id")) for row in raw_rows if isinstance(row, dict) and row.get("task_id")})
+    multiple_tasks = len(task_ids) > 1
+    rewritten: list[dict[str, Any]] = []
+    for row in raw_rows:
+        if not isinstance(row, dict):
+            continue
+        rel = str(row.get("package_relative_path") or "")
+        task_id = str(row.get("task_id") or "")
+        if not rel or not task_id or is_unsafe_bundle_ref(rel):
+            rewritten.append(sanitize_public_obj(row))
+            continue
+        src = release_root / "packages" / task_id / rel
+        bundle_rel = f"packages/{task_id}/{rel}" if multiple_tasks else rel
+        clean_row = sanitize_public_obj(dict(row))
+        clean_row["package_relative_path"] = bundle_rel
+        if src.exists() and _copy_public_file(src, bundle_root / bundle_rel):
+            clean_row.pop("artifact_missing", None)
+        else:
+            clean_row["artifact_missing"] = True
+        rewritten.append(clean_row)
+    write_json(bundle_root / "outputs" / "artifacts_index.json", rewritten)
+
+
+def is_unsafe_bundle_ref(ref: str) -> bool:
+    path = Path(ref)
+    return path.is_absolute() or ".." in path.parts
+
+
 def _first_jsonl_row(path: Path) -> dict[str, Any]:
     rows = read_jsonl(path) if path.exists() else []
     for row in rows: