@agentled/cli/dist/utils/workspace-folder.d.ts

CLI for Agentled — manage workflows, apps, and knowledge from the command line. Zero context-window cost for AI agents.

/**
 * Workspace folder helpers — local agentled_<slug>/ directory used as the
 * agent's working tree for building, testing, and iterating on workflows.
 *
 * Folder layout:
 *
 *   agentled_<slug>/
 *   ├── README.md                # agent-facing guide
 *   ├── AGENTS.md                # Codex/agent guidance for this client workspace
 *   ├── .agentled/
 *   │   ├── workspace.json       # workspaceId, slug, apiBase, syncedAt
 *   │   └── cache/
 *   │       ├── apps.json        # app registry
 *   │       └── models.json      # supported models
 *   ├── docs/
 *   │   ├── SKILL.md             # full skill reference (copied from package)
 *   │   └── GOTCHAS.md           # documented failure modes
 *   ├── examples/
 *   │   ├── scaffolds/           # bundled scaffold JSONs (editable)
 *   │   └── live/                # workflows pulled from the workspace
 *   ├── fixtures/
 *   │   └── step-outputs/        # captured step outputs (zero-credit replay)
 *   ├── tests/                   # <wfId>.test.json declarative test files
 *   ├── tasks/                   # local DFE task tracking, not workspace KG
 *   └── drafts/                  # in-progress pipeline JSON files
 */
import type { WorkspaceMeta } from './workspace-meta.js';
export { resolveWorkspaceMeta, slugifyWorkspaceRef, type WorkspaceMeta } from './workspace-meta.js';
export declare function findWorkspaceDir(cwd?: string): string | null;
export declare function readWorkspaceMeta(wsDir: string): WorkspaceMeta;
export declare function writeWorkspaceMeta(wsDir: string, meta: WorkspaceMeta): void;
export declare function bundledScaffoldsDir(): string;
export declare function bundledSkillMd(): string;
/** Progressive-disclosure reference docs that SKILL.md links to. */
export declare function bundledSkillReferencesDir(): string;
export declare const GOTCHAS_MD = "# Agentled \u2014 Documented Failure Modes (GOTCHAS)\n\nThese pass JSON syntax validation but silently misbehave at runtime.\nRun `agentled workflows lint <file>` to catch them statically before deploying.\n\n---\n\n## 1. `criteria` not `conditions` in entryConditions  [CRITERIA_NOT_CONDITIONS]\n\n**Wrong:** `{ \"entryConditions\": { \"conditions\": [...] } }`\n**Correct:** `{ \"entryConditions\": { \"criteria\": [...] } }`\n\nThe executor reads `entryConditions.criteria`. The key `conditions` is silently ignored.\n\n---\n\n## 2. `variable` not `field` in criteria items  [VARIABLE_NOT_FIELD]\n\n**Wrong:** `{ \"field\": \"{{steps.x.score}}\", \"operator\": \">\", \"value\": 70 }`\n**Correct:** `{ \"variable\": \"{{steps.x.score}}\", \"operator\": \">\", \"value\": 70 }`\n\nUsing `field` causes the criterion to be silently skipped.\n\n---\n\n## 3. Gmail label_id must be the internal Label_XXXX ID  [GMAIL_LABEL_DISPLAY_NAME]\n\nGmail's API requires `Label_XXXXXXXXXX` IDs, not display names.\nAdd a `GMAIL_CREATE_LABEL` step before and use `{{steps.ensure-label.id}}`.\n\n---\n\n## 4. `aiActionWithTools` with no tools  [AI_STEP_TOOLS_REQUIRED]\n\nA step with `type: \"aiActionWithTools\"` must have at least one tool in\n`step.tools` or `step.agent.tools`.\n\nValid `builtinType` values: `web_search`, `file_search`, `code_interpreter`,\n`fetch_website_content`, `kg_search`, `kg_traverse`, `kg_nodes`, `kg_write`,\n`workspace_memory`.\n\n---\n\n## 5. Email steps need type + approval action + outreachProfile  [EMAIL_MISSING_*]\n\nThree required pieces:\n- `pipelineStepPrompt.type: \"email\"`\n- `onApproval.action: \"schedule-email\"`\n- `outreachProfile` input page in `context.inputPages`\n\nMissing the schedule-email action means the email is drafted but never sent.\n\n---\n\n## 6. Only the first step in a loop gets `loopConfig`  [LOOP_CONFIG_MULTIPLE_STEPS]\n\n`loopConfig` must be on the first step in the loop chain only. Subsequent\nsteps inside the loop iterate automatically.\n\n---\n\n## 7. Don't pass raw `{{input.*}}` directly to search APIs  [RAW_INPUT_TO_SEARCH]\n\nAdd an aiAction step before the search that generates optimized queries.\nRaw user input makes poor search queries.\n\n---\n\n## 8. Child workflows must use `return` step, not `milestone`  [CHILD_WORKFLOW_NO_RETURN]\n\nIf a workflow is called via `agentled.call-workflow`, use `type: \"return\"`.\n`milestone` produces no return data. Also set `context.executionInputConfig.internal: true`.\n\n---\n\n## 9. Model IDs are internal format, not Anthropic format  [MODEL_ID_FORMAT]\n\nWrong: `claude-sonnet-4-6`. Correct: `claude-4-6-sonnet`.\nRun `agentled models list` for valid internal IDs.\n\n---\n\n## 10. Native app actionId must include appId prefix  [ACTION_ID_MISSING_PREFIX]\n\nWrong: `{ \"id\": \"kg\", \"actionId\": \"read-list\" }`\nCorrect: `{ \"id\": \"kg\", \"actionId\": \"kg.read-list\" }`\n\n---\n\n## 11. `loop_completion` criteria requires `onCriteriaFail: \"wait\"`  [LOOP_COMPLETION_NOT_WAIT]\n\nWithout `onCriteriaFail: \"wait\"`, the step skips instead of blocking until\nthe loop finishes. The `stepId` field is also required.\n\n---\n\n## 12. Arrays in JSON template strings \u2014 don't JSON.stringify\n\nThe serializer detects when a template variable is the sole content of a JSON\nfield and inlines the raw value. Pass `{ \"items\": \"{{steps.x.items}}\" }`\ndirectly \u2014 no stringify needed.\n\n---\n\n## 13. `kg.upsert-rows` needs `userKey` for dedup; `kg.add-rows` always inserts\n\n`kg.upsert-rows` with `userKey`: same key = same row, cross-run dedup O(1).\n`kg.add-rows`: always inserts a new row, duplicates accumulate.\nUse `mergeStrategy: \"merge\"` to preserve downstream-added fields.\n";
export declare const TASKS_README_MD = "# Tasks\n\nUse this folder for local DFE execution work for this client workspace:\n\n- active tasks and follow-ups\n- implementation notes\n- blockers and open questions\n- done logs and handoff notes\n\nKeep task-level details local. They are operational, may be noisy or provisional, and should not be synced wholesale into workspace knowledge.\n\nPromote only client-facing milestone recaps and alignment memory to workspace `kg.text`:\n\n- delivered milestones\n- agreed decisions\n- important blockers or risks\n- next client-facing follow-ups\n- context the client or future agent sessions need to stay aligned\n\nDo not store secrets or connector credentials in this folder.\n";
export declare function makeAgentsMd(meta: WorkspaceMeta): string;
export declare function makeWorkspaceReadme(meta: WorkspaceMeta): string;
export declare function createWorkspaceFolder(folderPath: string, meta: WorkspaceMeta, opts?: {
    appsList?: unknown;
    modelsList?: unknown;
}): void;
export declare function refreshWorkspaceFolder(wsDir: string, opts: {
    appsList?: unknown;
    modelsList?: unknown;
}): void;