use-agent 1.0.0b1__py3-none-any.whl

use_agent/__init__.py

@@ -0,0 +1,8 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version('use-agent')
+except importlib.metadata.PackageNotFoundError:
+    __version__ = '0.0.0+unknown'
+
+__all__ = ['__version__']

use_agent/__main__.py

@@ -0,0 +1,4 @@
+from use_agent.cli import main
+
+if __name__ == '__main__':
+    main()

use_agent/agent.py

@@ -0,0 +1,281 @@
+"""Orchestrates a Claude Agent run over the Gmail inbox."""
+
+import logging
+
+import claude_agent_sdk
+import jinja2
+
+from use_agent import (
+    auth,
+    config,
+    gmail,
+    tools,
+)
+from use_agent import (
+    reporter as reporter_mod,
+)
+from use_agent import (
+    settings as settings_mod,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+
+SYSTEM_PROMPT_TEMPLATE = """\
+You are use-agent, a triage assistant for {{ user_name }}'s Gmail
+inbox. Your job is to find unsolicited sales email ("cold sales"),
+reply to it on {{ user_name }}'s behalf in their voice, and then
+archive the thread.
+
+You have the following tools (prefixed with ``mcp__gmail__``):
+- ``search``: run a Gmail search query, returns message ids
+- ``get_message``: fetch full message (headers, body, thread state)
+- ``reply``: send a threaded reply to a message
+- ``archive_and_mark_read``: archive the thread and mark it read
+
+## Workflow
+
+1. Call ``search`` with the query provided in the user message.
+2. For each returned message, call ``get_message``.
+3. Skip any message where ``thread_replied`` is true, where the
+   sender domain is in the safelist below, or where the classifier
+   result is not COLD_SALES.
+4. For each COLD_SALES message, generate a reply body using the
+   reply rules below, then call ``reply`` with that body. On
+   success, call ``archive_and_mark_read``.
+5. If ``dry_run`` is true, do everything except call ``reply`` and
+   ``archive_and_mark_read``. Still report what you would have done.
+6. When finished, emit a single fenced JSON block (no other JSON
+   in your output) with a top-level ``results`` array. One entry
+   per examined message; each entry has these keys:
+
+   - ``sender``: the original ``From`` header, including name
+   - ``subject``: the original subject
+   - ``classification``: ``COLD_SALES`` or ``NOT_COLD_SALES``
+   - ``score``: integer
+   - ``response_mode``: ``hard_remove``,
+     ``hard_remove_with_correction``, ``specific_decline``, or
+     ``none``
+   - ``action_taken``: one of ``Reply sent & archived``,
+     ``Dry-run: would reply & archive``,
+     ``Skipped (not cold sales)``, ``Skipped (already replied)``,
+     or ``Error: <detail>``
+
+   Use a ```` ```json ```` fence. The block is parsed by the host
+   program, so it must be valid JSON.
+
+Never invent or fabricate email content. Never send anything other
+than the reply text produced by the reply rules. If a tool fails,
+record the error in the corresponding ``action_taken`` field and
+continue with the next message.
+
+## Safelist domains
+
+{% if safelist_domains %}
+Treat senders from any of these domains as internal. Never classify
+them as cold sales and never reply:
+
+{% for d in safelist_domains %}
+- {{ d }}
+{% endfor %}
+{% else %}
+(none configured)
+{% endif %}
+
+## Classification rules
+
+{{ classifier }}
+
+## Reply rules
+
+{{ reply }}
+"""
+
+
+def _jinja_env() -> jinja2.Environment:
+    return jinja2.Environment(
+        loader=jinja2.FileSystemLoader(str(config.PROMPTS_DIR)),
+        autoescape=False,  # noqa: S701 - prompts are fed to an LLM, not rendered as HTML
+        keep_trailing_newline=True,
+        undefined=jinja2.StrictUndefined,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+
+def _render_template(
+    env: jinja2.Environment,
+    name: str,
+    settings: settings_mod.Settings,
+) -> str:
+    template = env.get_template(name)
+    return template.render(_render_context(env, settings))
+
+
+def _render_context(
+    env: jinja2.Environment,
+    settings: settings_mod.Settings,
+) -> dict[str, object]:
+    base = {
+        'user_name': settings.user_name,
+        'organization': settings.organization,
+        'safelist_domains': list(settings.safelist_domains),
+        'vendor_names': list(settings.vendor_names),
+        'voice_guidelines': list(settings.voice_guidelines),
+    }
+    # The footer may itself be a Jinja string (e.g. "{{ user_name }}").
+    rendered_footer = (
+        env.from_string(settings.reply_footer).render(base)
+        if settings.reply_footer
+        else ''
+    )
+    voice_block = '\n'.join(f'- {g}' for g in settings.voice_guidelines)
+    # Example bullets may themselves contain Jinja refs like
+    # {{ organization }}; render each one against the base context
+    # before joining so interpolation happens exactly once.
+    hard_remove_examples = _render_examples(
+        env, settings.examples_hard_remove, base
+    )
+    hard_remove_with_correction_examples = _render_examples(
+        env, settings.examples_hard_remove_with_correction, base
+    )
+    specific_decline_examples = _render_examples(
+        env, settings.examples_specific_decline, base
+    )
+    # Pre-rendered blocks are inserted verbatim so prompt markdown
+    # stays free of Jinja control flow (formatters don't preserve
+    # blank lines inside {% if %} blocks).
+    if rendered_footer:
+        footer_block = f'\n\n{rendered_footer}'
+        footer_instruction = (
+            'Every reply must end with the following footer, '
+            'appended after the reply body on a new line, '
+            'separated by a blank line:\n\n'
+            f'```\n{rendered_footer}\n```'
+        )
+    else:
+        footer_block = ''
+        footer_instruction = (
+            'No footer — send the reply body verbatim with no trailing text.'
+        )
+    return {
+        **base,
+        'reply_footer': rendered_footer,
+        'voice_block': voice_block,
+        'footer_block': footer_block,
+        'footer_instruction': footer_instruction,
+        'hard_remove_examples': hard_remove_examples,
+        'hard_remove_with_correction_examples': (
+            hard_remove_with_correction_examples
+        ),
+        'specific_decline_examples': specific_decline_examples,
+    }
+
+
+def _render_examples(
+    env: jinja2.Environment,
+    items: tuple[str, ...],
+    context: dict[str, object],
+) -> str:
+    """Render each example as a Markdown bullet.
+
+    An empty list collapses to the single line "(none configured)"
+    so the rendered prompt always has something under the heading.
+    """
+    if not items:
+        return '(none configured)'
+    bullets: list[str] = []
+    for item in items:
+        rendered = env.from_string(item).render(context).strip()
+        bullets.append(f'- "{rendered}"')
+    return '\n'.join(bullets)
+
+
+def _render_system_prompt(settings: settings_mod.Settings) -> str:
+    env = _jinja_env()
+    classifier = _render_template(env, config.CLASSIFIER_PROMPT.name, settings)
+    reply = _render_template(env, config.REPLY_PROMPT.name, settings)
+    system_template = jinja2.Environment(
+        autoescape=False,  # noqa: S701 - prompts are fed to an LLM, not rendered as HTML
+        keep_trailing_newline=True,
+        undefined=jinja2.StrictUndefined,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    ).from_string(SYSTEM_PROMPT_TEMPLATE)
+    return system_template.render(
+        user_name=settings.user_name,
+        safelist_domains=list(settings.safelist_domains),
+        classifier=classifier.strip(),
+        reply=reply.strip(),
+    )
+
+
+def _user_prompt(*, query: str, max_results: int, dry_run: bool) -> str:
+    return (
+        'Process the Gmail inbox now.\n\n'
+        f'search query: {query}\n'
+        f'max_results: {max_results}\n'
+        f'dry_run: {str(dry_run).lower()}\n'
+    )
+
+
+async def run(
+    *,
+    settings: settings_mod.Settings,
+    reporter: reporter_mod.Reporter,
+    query: str | None = None,
+    max_results: int | None = None,
+    dry_run: bool = False,
+) -> int:
+    """Execute a single agent pass over the inbox.
+
+    Returns a process exit code — 0 on a successful run with a
+    parsed summary, non-zero if the agent produced no summary.
+    """
+    effective_query = query or settings.search_query
+    effective_max = max_results or settings.max_results
+    creds = auth.load_credentials(
+        credentials_file=config.credentials_path(),
+        token_file=config.token_path(),
+        scopes=config.GMAIL_SCOPES,
+    )
+    client = gmail.GmailClient(creds)
+    server = tools.build_mcp_server(client)
+    options = claude_agent_sdk.ClaudeAgentOptions(
+        system_prompt=_render_system_prompt(settings),
+        mcp_servers={tools.MCP_SERVER_NAME: server},
+        allowed_tools=list(tools.ALLOWED_TOOLS),
+        permission_mode='acceptEdits',
+        model=settings.model,
+        # Isolate from the host's Claude Code setup: no user/project
+        # settings, no on-disk settings file, no auto-loaded skills.
+        # Only our Gmail MCP server and system prompt drive behavior.
+        setting_sources=[],
+        settings=None,
+        skills=None,
+    )
+    prompt = _user_prompt(
+        query=effective_query,
+        max_results=effective_max,
+        dry_run=dry_run,
+    )
+    LOGGER.info(
+        'starting agent run: query=%r max=%d dry_run=%s model=%s',
+        effective_query,
+        effective_max,
+        dry_run,
+        settings.model,
+    )
+    async for message in claude_agent_sdk.query(
+        prompt=prompt, options=options
+    ):
+        _forward(message, reporter)
+    return reporter.finish()
+
+
+def _forward(message: object, reporter: reporter_mod.Reporter) -> None:
+    """Feed assistant text blocks to the reporter."""
+    if isinstance(message, claude_agent_sdk.AssistantMessage):
+        for block in message.content:
+            if isinstance(block, claude_agent_sdk.TextBlock):
+                reporter.on_text(block.text)

use_agent/auth.py

@@ -0,0 +1,60 @@
+"""Google OAuth installed-app flow for Gmail."""
+
+import logging
+import pathlib
+
+import google.auth.transport.requests
+import google.oauth2.credentials
+import google_auth_oauthlib.flow
+
+LOGGER = logging.getLogger(__name__)
+
+
+def load_credentials(
+    *,
+    credentials_file: pathlib.Path,
+    token_file: pathlib.Path,
+    scopes: tuple[str, ...],
+) -> google.oauth2.credentials.Credentials:
+    """Return valid Credentials, running the OAuth flow if needed.
+
+    If a token file exists, load and refresh it. Otherwise, run the
+    installed-app browser flow using ``credentials_file`` and persist
+    the resulting token.
+    """
+    creds: google.oauth2.credentials.Credentials | None = None
+    if token_file.exists():
+        creds = (
+            google.oauth2.credentials.Credentials.from_authorized_user_file(
+                str(token_file), list(scopes)
+            )
+        )
+    if creds and creds.valid:
+        return creds
+    if creds and creds.expired and creds.refresh_token:
+        LOGGER.info('refreshing Gmail OAuth token')
+        creds.refresh(google.auth.transport.requests.Request())
+        _write_token(token_file, creds)
+        return creds
+    if not credentials_file.exists():
+        raise FileNotFoundError(
+            f'OAuth client secret not found at {credentials_file}. '
+            'Create one in Google Cloud Console (Desktop app) and '
+            'place it there, or set USE_AGENT_CREDENTIALS.'
+        )
+    LOGGER.info('running OAuth installed-app flow')
+    flow = google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file(
+        str(credentials_file), list(scopes)
+    )
+    creds = flow.run_local_server(port=0)
+    _write_token(token_file, creds)
+    return creds
+
+
+def _write_token(
+    path: pathlib.Path,
+    creds: google.oauth2.credentials.Credentials,
+) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(creds.to_json())
+    path.chmod(0o600)

use_agent/cli.py

@@ -0,0 +1,202 @@
+"""Command-line entry point for use-agent."""
+
+import argparse
+import asyncio
+import logging
+import pathlib
+import re
+import sys
+
+from use_agent import agent, auth, config, reporter
+from use_agent import settings as settings_mod
+
+LOGGER = logging.getLogger(__name__)
+
+_INTERVAL_RE = re.compile(r'^(?P<n>\d+)(?P<unit>[smhd]?)$')
+_UNIT_SECONDS = {'': 1, 's': 1, 'm': 60, 'h': 3600, 'd': 86400}
+DEFAULT_INTERVAL_SECONDS = 15 * 60
+
+
+def _parse_interval(raw: str) -> int:
+    match = _INTERVAL_RE.fullmatch(raw.strip().lower())
+    if not match:
+        raise argparse.ArgumentTypeError(
+            f'invalid interval {raw!r}; use e.g. 30s, 15m, 2h, 1d'
+        )
+    seconds = int(match.group('n')) * _UNIT_SECONDS[match.group('unit')]
+    if seconds <= 0:
+        raise argparse.ArgumentTypeError(
+            f'interval must be positive, got {raw!r}'
+        )
+    return seconds
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog='use-agent',
+        description=('Claude Agent that triages cold sales email in Gmail.'),
+    )
+    parser.add_argument(
+        '-v',
+        '--verbose',
+        action='store_true',
+        help='enable debug logging',
+    )
+    parser.add_argument(
+        '--logfile',
+        type=pathlib.Path,
+        default=None,
+        help='append structured logs to this file (in addition to stderr)',
+    )
+    sub = parser.add_subparsers(dest='command', required=True)
+
+    sub.add_parser(
+        'auth',
+        help='run the Gmail OAuth flow and save credentials',
+    )
+
+    run_p = sub.add_parser('run', help='process the inbox once')
+    run_p.add_argument(
+        '--query',
+        default=None,
+        help=(
+            'override the Gmail search query; defaults to the one '
+            'in config.toml (or one built from the safelist)'
+        ),
+    )
+    run_p.add_argument(
+        '--max',
+        dest='max_results',
+        type=int,
+        default=None,
+        help='override maximum candidates to examine',
+    )
+    run_p.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='classify only; do not reply or archive',
+    )
+    run_p.add_argument(
+        '--daemon',
+        action='store_true',
+        help='run continuously; re-process the inbox every --interval',
+    )
+    run_p.add_argument(
+        '--interval',
+        type=_parse_interval,
+        default=DEFAULT_INTERVAL_SECONDS,
+        help='daemon interval (e.g. 30s, 15m, 2h); default 15m',
+    )
+    out = run_p.add_mutually_exclusive_group()
+    out.add_argument(
+        '--plain',
+        dest='output',
+        action='store_const',
+        const=reporter.Mode.PLAIN,
+        help='disable ANSI colours and render a pipe-delimited table',
+    )
+    out.add_argument(
+        '--json',
+        dest='output',
+        action='store_const',
+        const=reporter.Mode.JSON,
+        help='emit only the parsed summary as JSON on stdout',
+    )
+    run_p.set_defaults(output=reporter.Mode.PRETTY)
+    return parser
+
+
+def _configure_logging(*, verbose: bool, logfile: pathlib.Path | None) -> None:
+    # Log to stderr so --json stdout stays parseable.
+    level = logging.DEBUG if verbose else logging.INFO
+    fmt = '%(asctime)s %(levelname)s %(name)s: %(message)s'
+    handlers: list[logging.Handler] = [logging.StreamHandler(sys.stderr)]
+    if logfile is not None:
+        logfile.parent.mkdir(parents=True, exist_ok=True)
+        handlers.append(logging.FileHandler(logfile, encoding='utf-8'))
+    logging.basicConfig(
+        level=level,
+        format=fmt,
+        handlers=handlers,
+        force=True,
+    )
+    # SDK's own INFO stream is too chatty for our usage.
+    logging.getLogger('claude_agent_sdk').setLevel(logging.WARNING)
+
+
+def _cmd_auth() -> int:
+    creds_file = config.credentials_path()
+    token_file = config.token_path()
+    auth.load_credentials(
+        credentials_file=creds_file,
+        token_file=token_file,
+        scopes=config.GMAIL_SCOPES,
+    )
+    print(f'Gmail credentials stored at {token_file}')  # noqa: T201
+    return 0
+
+
+async def _run_once(
+    settings: settings_mod.Settings,
+    args: argparse.Namespace,
+) -> int:
+    rpt = reporter.Reporter(mode=args.output)
+    return await agent.run(
+        settings=settings,
+        reporter=rpt,
+        query=args.query,
+        max_results=args.max_results,
+        dry_run=args.dry_run,
+    )
+
+
+async def _run_daemon(
+    settings: settings_mod.Settings,
+    args: argparse.Namespace,
+) -> int:
+    interval = args.interval
+    LOGGER.info('daemon mode: every %ds (Ctrl-C to stop)', interval)
+    while True:
+        try:
+            rc = await _run_once(settings, args)
+            LOGGER.info('iteration finished (rc=%d)', rc)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            LOGGER.exception('iteration failed, continuing')
+        try:
+            await asyncio.sleep(interval)
+        except asyncio.CancelledError:
+            raise
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    settings = settings_mod.Settings.load()
+    coro = (
+        _run_daemon(settings, args)
+        if args.daemon
+        else _run_once(settings, args)
+    )
+    try:
+        return asyncio.run(coro)
+    except KeyboardInterrupt:
+        LOGGER.info('interrupted; shutting down')
+        return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    _configure_logging(verbose=args.verbose, logfile=args.logfile)
+    match args.command:
+        case 'auth':
+            return _cmd_auth()
+        case 'run':
+            return _cmd_run(args)
+        case _:  # pragma: no cover - argparse enforces choices
+            parser.error(f'unknown command: {args.command}')
+            return 2
+
+
+if __name__ == '__main__':
+    sys.exit(main())

use_agent/config.py

@@ -0,0 +1,44 @@
+"""Paths and static defaults for use-agent."""
+
+import os
+import pathlib
+
+# Single scope. gmail.modify covers read, label changes, and send.
+GMAIL_SCOPES: tuple[str, ...] = (
+    'https://www.googleapis.com/auth/gmail.modify',
+)
+
+PROMPTS_DIR: pathlib.Path = pathlib.Path(__file__).parent / 'prompts'
+CLASSIFIER_PROMPT: pathlib.Path = PROMPTS_DIR / 'classifier.md'
+REPLY_PROMPT: pathlib.Path = PROMPTS_DIR / 'reply.md'
+
+
+def _config_home() -> pathlib.Path:
+    raw = os.environ.get('XDG_CONFIG_HOME')
+    if raw:
+        return pathlib.Path(raw) / 'use-agent'
+    return pathlib.Path.home() / '.config' / 'use-agent'
+
+
+def credentials_path() -> pathlib.Path:
+    """Path to the Google OAuth client secret JSON."""
+    override = os.environ.get('USE_AGENT_CREDENTIALS')
+    if override:
+        return pathlib.Path(override)
+    return _config_home() / 'credentials.json'
+
+
+def token_path() -> pathlib.Path:
+    """Path to the stored OAuth refresh token."""
+    override = os.environ.get('USE_AGENT_TOKEN')
+    if override:
+        return pathlib.Path(override)
+    return _config_home() / 'token.json'
+
+
+def config_file_path() -> pathlib.Path:
+    """Path to the TOML configuration file."""
+    override = os.environ.get('USE_AGENT_CONFIG')
+    if override:
+        return pathlib.Path(override)
+    return _config_home() / 'config.toml'