Function agenticToolGuidance

packages/core/src/agent.ts:483–538

(input: {
  inspectWorkspace: boolean;
  featureProfile: PromptFeatureProfile;
  currentDesignName?: string | undefined;
})

}

function agenticToolGuidance(input: {
  inspectWorkspace: boolean;
  featureProfile: PromptFeatureProfile;
  currentDesignName?: string | undefined;
}): string {
  const titleStep = isAutoDesignName(input.currentDesignName)
    ? '1. The current design title is still auto-generated. Call `set_title` once as the first tool call, before `set_todos`, `view`, `scaffold`, or file edits. Use a 2-5 word title that describes what is being designed.'
    : '1. For a fresh design, call `set_title` once. For continuation or existing-source turns, do not call `set_title` unless the user explicitly asks to rename or pivot to a new artifact.';
  const tweakStep = explicitDisabled(input.featureProfile.tweaks)
    ? `${input.inspectWorkspace ? '6' : '5'}. Do not call \`tweaks()\` unless the user explicitly asks for controls later.`
    : featureModeValue(input.featureProfile.tweaks) === 'enabled'
      ? `${input.inspectWorkspace ? '6' : '5'}. Create 2-5 high-leverage EDITMODE controls, then call \`tweaks()\`.`
      : `${input.inspectWorkspace ? '6' : '5'}. Decide agentically whether \`tweaks()\` would materially improve iteration; do not rely on harness guesses.`;
  const requiredSteps = [
    titleStep,
    '2. For multi-step or ambiguous work, call `set_todos` early with a short checklist. Do not delay a ready file mutation solely to add todos.',
    '3. Load optional resources explicitly before relying on them. Use `skill(name)` for method guidance. When the request matches an available frame, shell, primitive, deck, report, or starter, call `scaffold({kind, destPath})` before writing the primary artifact; do not substitute a virtual `frames/*` or `skills/*` view for scaffolded workspace source.',
    ...(input.inspectWorkspace
      ? [
          '4. When the workspace brief says files or reference materials are present, call `inspect_workspace` before editing, then `view` the specific files you need.',
        ]
      : []),
    `${input.inspectWorkspace ? '5' : '4'}. Match the workspace files to the request. For visual/web work, write/edit the primary preview source at \`${DEFAULT_SOURCE_ENTRY}\`; for document-first work, create the requested Markdown/handoff file without inventing a visual shell.`,
    tweakStep,
    `${input.inspectWorkspace ? '7' : '6'}. Call \`preview(path)\` for previewable HTML/JSX/TSX files after the final mutation, then call \`done(path)\` as the final self-check. If done reports errors, fix and retry, but stop after ${MAX_DONE_ERROR_ROUNDS} error rounds.`,
  ];
  return [
    '## Workspace output contract',
    '',
    '- The workspace filesystem is the deliverable. Chat text is never the artifact.',
    `- For visual/web deliverables, write the primary design source to \`${DEFAULT_SOURCE_ENTRY}\` with \`str_replace_based_edit_tool\`.`,
    '- Multi-deliverable packages are allowed when useful: preview source, DESIGN.md, Markdown handoff docs, data files, and local assets can all belong to one design.',
    '- For document-first requests such as design briefs, content outlines, or handoff notes, create the requested `.md` file directly and skip `App.jsx` unless a visual preview is also useful.',
    '- Prefer progressive generation when it is natural: write a coherent first pass, then add sections, data, interactions, and polish in focused edits before previewing.',
    '- Fresh visual sequence: `set_title` -> optional `set_todos`/`skill` -> required `scaffold` when a matching starter/frame/shell/primitive exists -> `create App.jsx` with a coherent first pass -> focused edits if needed -> `preview(App.jsx)`.',
    '- Fresh document sequence: `set_title` -> optional `set_todos`/`skill` -> create the requested document file -> `done(path)` self-check.',
    '- Do not call `preview` while a previewable artifact is still only a scaffold, loading state, skeleton, placeholder, or empty lower section. Preview should represent a coherent first pass unless the user explicitly asked for a loading-state design.',
    '- Existing-source sequence: optional `set_todos` -> `inspect_workspace` when available -> `view` the source -> `str_replace`/`insert`. Do not edit an existing source from memory, and do not rebuild unless the user explicitly asks.',
    '- If the design is still named `Untitled design` or `Untitled design N`, naming is not optional: call `set_title` before other work, even when a scaffold or reference source already exists.',
    '- Use `create` for new files; follow-up edits use `view`, `str_replace`, or `insert`.',
    '- Do not emit `<artifact>` tags, fenced source blocks, raw HTML/JSX/CSS, or HTML wrappers in chat.',
    '- Local workspace assets and scaffolded files are allowed. External scripts remain restricted by the base output rules.',
    '- Interleave major tool groups with one short assistant progress sentence: what you are about to inspect/write/preview/fix, or what the preview showed. Keep it under 18 words and do not reveal hidden reasoning.',
    '',
    '## Tool loop',
    '',
    ...requiredSteps,
    '',
    '## File-edit discipline',
    '',
    '- Keep `old_str` small and unique. Large replacements waste context and are fragile.',
    '- For existing files, call `view` in the same run before `str_replace` or `insert`; use the latest viewed text, not memory.',
    '- A complete first `create` is acceptable when the target file is ready. Keep follow-up edits focused so they remain reliable.',
    '- Never view just to check whether an edit succeeded; the tool reports failures.',
  ].join('\n');
}

const IMAGE_ASSET_TOOL_GUIDANCE = [