Expose avatar_handle constraints in CLI tool schemas

[chasehuh]

Summary

Dogfooding showed that sume tools schema avatars.create does not expose the public avatar_handle length/pattern constraints, even though the live API/OpenAPI does. A fresh agent generated a too-long handle, hit API validation, then had to retry with a shorter handle.

This is a CLI/tool-schema drift issue. The API source of truth is already more precise; the CLI schema should mirror it so agents can avoid invalid paid-submit attempts before they reach the API.

Evidence

Audited local CLI:

sumelabs/cli main @ 63f09de642501b0cdfd86f9a8d64916532ad0386
CLI version 0.1.1

Current CLI tool schema summary:

/Users/huhchaewon/sume/cli/dist/sume --json tools schema avatars.create

Observed input_schema.properties.avatar_handle:

{
  "type": "string",
  "description": "Desired canonical public avatar handle, without @."
}

Observed input_schema.properties.handle:

{
  "type": "string",
  "description": "Alias for avatar_handle."
}

There is no minLength, maxLength, or pattern in the CLI tool schema.

Live OpenAPI source of truth does include the constraints. Read-only fetch of https://api.sume.com/reference/json with a user-agent showed components.schemas.AvatarModelRunRequest.properties.avatar_handle has:

{
  "type": "string",
  "minLength": 2,
  "maxLength": 31,
  "pattern": "^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$"
}

The same pattern/max length also appears for Avatar Video create.

Dogfood impact

In the PR #12 dogfood thread, the agent attempted Avatar creation with a long generated handle. The API rejected it with a validation error because the handle exceeded the public limit. The agent recovered by retrying with a shorter handle, but this is exactly the type of error the local tool schema is supposed to prevent.

No new provider/paid job was needed to validate this issue; the schema mismatch is visible through local CLI schema export and live OpenAPI readback.

Expected behavior

tools schema avatars.create should expose the same public handle constraints as the launch OpenAPI, including at least:

• minLength: 2
• maxLength: 31
• handle pattern or equivalent explicit description
• reserved prefix caveat if applicable to public Avatar creation

The alias field handle should carry equivalent constraints or clearly reference avatar_handle.

Also check avatar-videos.create and any batch manifest schemas/examples that accept avatar_handle so agents can generate valid handles consistently.

Acceptance criteria

• sume tools schema avatars.create --json includes minLength, maxLength, and pattern/constraint guidance for avatar_handle.
• The handle alias is equally constrained or clearly documented as an alias of avatar_handle.
• sume tools schema avatar-videos.create --json remains aligned with live OpenAPI handle constraints.
• Skill examples and batch manifest docs use handles within the valid length/pattern.
• Tests assert the CLI tool registry does not regress against these constraints.
• No old sume.so surfaces or provider/internal fields are introduced.

Suggested implementation

Update src/lib/tool-registry.ts shared avatar_handle schema definitions if present, or add a shared handle schema object used by Avatar and Avatar Video tool definitions. Add focused tests in test/cli.test.ts or tool-registry tests that inspect the JSON schema for handle constraints.

[chasehuh]

Fixed by #14. The merged CLI tool schemas now expose the live OpenAPI avatar_handle minLength, maxLength, and pattern constraints on avatars.create and avatar-videos.create.