---
name: im-update-agent
description: Bring an EXISTING local in·manas agent project up to the current im-sdk. Use when the user wants to "update an agent/project", "bump the SDK", "upgrade im-sdk in this project", "my agent is on an old SDK", or "migrate this project to the latest SDK". Detects the project's pinned im-sdk, migrates any breaking-change code in main.py (e.g. llm `model=`→`alias=`, the canonical ResourceResult envelope, `manifest_version`→`kind`) using the bundled SDK reference, re-locks against the public index, cleans now-stale scaffold bits (deletes .im/manifest.json and the .env — workspace and the run's agent secret are runner-injected; the .env is loaded and shipped today, so each other setting or token first moves to an org variable or secret), and stops before pushing — offering a manual `im-cli push` then `im-cli run`. Needs no monorepo: only the installed im-sdk and the im-cli CLI. For CREATING a new project from scratch, use im-create-agent instead.
---

# in·manas — Update a project to the current SDK

Take an **existing** local in·manas agent project and bring it to the **current `im-sdk`**:
migrate any code the SDK has broken, bump + re-lock the dependency, and clear out
scaffold artifacts that newer CLI/SDK versions no longer use. The end state is a project
that `im-cli push` will install cleanly with `uv sync --frozen`.

This skill **edits an existing project**; it does not scaffold one. To go from a prompt to
a new project, use [`im-create-agent`](../im-create-agent/SKILL.md).

**No monorepo needed.** It needs the installed `im-sdk` package and the `im-cli` CLI —
nothing from the sibling skill any more, now that the SDK resolves from a public index and
there is no wheel to vendor. Signatures come from the bundled [`references/sdk-reference.md`](references/sdk-reference.md);
the CLI surface from [`references/cli-reference.md`](references/cli-reference.md); known
breaking changes from [`references/migrations.md`](references/migrations.md). Monorepo-only
shortcuts are called out as such.

## When to use

- "Update / upgrade this agent" / "bump im-sdk to the latest"
- "My project is pinned to an old SDK" / "push fails after an SDK release"
- A project (any directory) with a `main.py` importing `im_sdk` + a `pyproject.toml`
  pinning `im-sdk`

Not for: creating a new project (→ `im-create-agent`), editing the SDK itself, or
Portal UI work.

---

## Phase 0 — Locate the project + read both versions

Point `$PROJ` at the project dir (it has `main.py` importing `im_sdk` + a `pyproject.toml`
with a `im-sdk` dependency):

```bash
PROJ=<the project dir>

# Pinned version + how the SDK is sourced:
grep -n 'im-sdk==' "$PROJ/pyproject.toml"
grep -n 'im_sdk-.*\.whl\|tool.uv.sources\|tool.uv.index' "$PROJ/pyproject.toml"
```

**What you'll find, and what it should become:**
- **The public index** (the only end state, and where Phase 2 puts every project) —
  `[[tool.uv.index]]` named `in-manas` at `https://downloads.mgt-platform.com/simple/` with
  `explicit = true`, plus `im-sdk = { index = "in-manas" }`. No credential anywhere; the
  agent slot resolves it exactly as your machine does.
- **A `gitlab-mgt` index** — an older scaffold pointing at the GitLab package registry.
  Dead: that registry is no longer published to, and it wanted a token. Repoint it at the
  public index (Phase 2).
- **A vendored wheel** — `[tool.uv.sources]` has
  `im-sdk = { path = "vendor/im_sdk-<v>-py3-none-any.whl" }`. It still installs, but it
  silently freezes the project on whatever wheel is in `vendor/`. Drop the `path` source and
  the `vendor/` directory and re-lock against the index (Phase 2).

**Target version = the latest published `im-sdk`.** You don't have to know the number up
front — Phase 2 resolves it. To see what's installed in your environment:

```bash
python -c "import importlib.metadata as m; print(m.version('im-sdk'))"
```

> **In the monorepo** the target is the working-tree SDK: `grep '^version' apps/core-sdk/pyproject.toml`.

If the pinned version already equals the target, the SDK is current — still run Phase 3
(stale-file cleanup) for older scaffolds, then stop.

---

## Phase 1 — Migrate breaking changes (only if the code uses the changed surface)

Read [`references/migrations.md`](references/migrations.md) for known breaking changes and
their symptom→fix, and [`references/sdk-reference.md`](references/sdk-reference.md) for the
current signatures + result shapes. Apply only the changes the project's `main.py` actually
hits. The most common, by far:

- **LLM is alias-only.** `core.llm.call(..., model="…")` → `core.llm.call(..., alias="…")`.
  Same for `stream` / `call_structured`.
- **Canonical `ResourceResult` envelope.** No `.content` and no per-resource
  `SearchResult`/`ExtractResult` shapes. Read the answer off the typed variant: `.text`
  (LLM), `.citations` (search hits), `.output.blocks`/`.pages`/`.elements`/`.items`/`.body`.
  List items are typed models — `hit.url`, not `hit["url"]`.
- **`core.manifest_version` was removed** → use `core.kind` / `core.granted_resources`.
- **`ImCore(...)` is keyword-only** (#655). A positional call
  `ImCore("agent-id", "secret", "ws-id", url)` raises `TypeError`; rewrite it as
  `ImCore(agent_id=…, workspace_id=…, base_url=…)` — and most agents should not construct it at
  all (`ImCore.from_env()` reads everything the runner injects).
- **`CIU_` agent names → `IM_`** (im-sdk 1.2.1). Only when the new pin is ≥ 1.2.1: rename
  `CIU_CHECKER_URL`, `CIU_RESUME_FILE`, `CIU_EMIT_PORTAL_EVENTS`, `CIU_LOG_LEVEL` and the
  tracing constants `CIU_SPAN_COMPLETED` / `CIU_TRACE_COMPLETE` / `CIU_TRACE_TREE` to their
  `IM_` names. The old names keep working, so this is tidying, not a fix. Leave every other
  `CIU_` name alone: those are the user's own org variables, and renaming one in code without
  renaming it in the Portal breaks the agent. `im-cli doctor` lists what is left.

For changes **newer than the bundled snapshot** (it reflects a specific SDK version — see its
header), verify against the **installed package** by introspection rather than guessing:

```bash
python -c "from im_sdk.resources.llm import LlmClient; import inspect; print(inspect.signature(LlmClient.call))"
python -c "import im_sdk; print([n for n in dir(im_sdk) if not n.startswith('_')])"   # top-level exports
```

Check the SDK's release notes / `CHANGELOG` for the version range. (Monorepo only: breaking
commits are tagged — `git log --oneline -- apps/core-sdk | grep -iE 'sdk\)!|manifest\)!'`.)

---

## Phase 2 — Bump the pin + re-lock

`im-cli push` installs with `uv sync --frozen`, so the lock must match the pin exactly.

### Re-lock against the public index

There is **no vendoring step**, and no second mode. It existed because the SDK lived on a
private index and an agent slot holds no credential, so an index-locked lock installed
nothing there. The SDK is published to the **public** in·manas index now, so the slot
resolves it the same way a laptop does (#464). A project still carrying `vendor/` and a
`path` source keeps working — but drop both and re-lock, or it silently stays on whatever
wheel was vendored.

1. Make `pyproject.toml` name the public index. Replace any `gitlab-mgt` index block, and
   any `im-sdk = { path = "vendor/…" }` source, with:

   ```toml
   [[tool.uv.index]]
   name = "in-manas"
   url = "https://downloads.mgt-platform.com/simple/"
   explicit = true

   [tool.uv.sources]
   im-sdk = { index = "in-manas" }
   ```

   `explicit = true` is load-bearing: without it `uv` searches this index for *every*
   dependency, and a public package sharing a name with something published here resolves
   from the wrong place. Delete `vendor/` if it exists.

2. Re-resolve. **No credential, no `UV_INDEX_*` environment, nothing to export** — the
   index and the wheels behind it are readable by anyone:

   ```bash
   cd "$PROJ"
   uv lock --upgrade-package im-sdk            # resolves the latest from the index
   grep -n 'im-sdk' uv.lock                    # note the resolved version
   # sync pyproject's `im-sdk==<resolved>` to match, then re-lock to confirm
   uv lock --upgrade-package im-sdk
   ```

   (If the `==` pin holds uv below the latest, loosen it to `im-sdk` for the first `uv lock`,
   read the resolved version, then re-pin `==<resolved>`. The pin is optional — an unpinned
   `im-sdk` plus a committed lock is equally exact.)

Your other dependencies keep resolving from PyPI, as they always did; it is the
*authenticated* fetch that disappeared, not the public one.

Commit `pyproject.toml` and `uv.lock` together — they are one unit.

`--upgrade-package` is required: plain `uv lock` won't re-resolve an already-satisfied
`im-sdk`, and `uv sync --locked` rejects a lock that drifted from the pin.

> **Deploying working-tree SDK changes (monorepo only).** Nothing published means nothing
> the index can serve, so this is the one case the index does not cover. Don't reintroduce a
> `vendor/` path source for it — build a wheel and overlay it into the agent's venv instead;
> see `apps/agent-runner/AGENTS.md`.

---

## Phase 3 — Clean now-stale scaffold artifacts

Older projects carry bits the current CLI/SDK no longer use:

- **`.im/manifest.json`** — `im-cli link` no longer writes a local manifest snapshot. Delete the
  file if present and drop the `manifest.json` line from `.im/.gitignore` (re-running
  `im-cli link` also rewrites the gitignore without it). Inspect grants live with `im-cli agent
  models` / `im-cli agent services` / `im-cli agent variables` instead (see [`references/cli-reference.md`](references/cli-reference.md)).
- **`.env` (and `.env.example`)** — **empty it first, then delete it.** The file is not inert:
  `@im_agent` loads it by default (`load_env=True`) and `im-cli push` ships it, so any value in it
  reaches today's deployed run. Go through it line by line **before** deleting:
  - `WORKSPACE_ID` and `AGENT_SECRET` — drop them. Both are runner-injected per execution, and
    the run's `AGENT_SECRET` is minted by Portal per run and checked at authorize (#655); a pinned
    one is at best ignored and at worst a stale value someone will copy.
  - **A setting** the code reads with `os.environ` / `os.getenv` (a base URL, a region, an ID) —
    move it to an org **variable** and read it as `core.vars["KEY"]`.
  - **A credential sent to a connected service** — move it to an org **secret** and write
    `core.secret("KEY")` in that call's params (im-sdk 1.2.0 or newer).
  - **A credential the code uses itself** (signs a request, opens a client the SDK does not
    route) — there is no safe destination for it: **stop and ask the user.** Never move a
    credential into the code.

  An admin creates and grants the variables and secrets; `im-cli agent variables` then shows the
  exact line to use. Delete `.env` only once every value has a home — deleting it first breaks a
  run that works today.
  > **Remove any hard-coded secret.** If `main.py` constructs `ImCore(...)` explicitly, leave
  > `agent_secret` out and drop any `"dev-secret"` / literal fallback: `ImCore` reads the
  > runner-injected `AGENT_SECRET` itself, and a literal would be refused at authorize. For a
  > host run (no runner, local stack only), export `AGENT_ID` / `WORKSPACE_ID` /
  > `IM_CHECKER_URL` instead of reintroducing a file.

> **Don't run the agent locally to "verify".** A `uv run` / `python main.py` creates `.venv/`
> + `__pycache__/` (zip bloat) and isn't a faithful signal — the real check is a Portal push +
> execution.

---

## Phase 4 — Hand off to push (don't auto-push)

The project is now on the current SDK. Summarize what changed (old→new version, migrations
applied, files cleaned) and offer the next step — **don't push automatically**:

- **Push** (already linked): from the project dir, `uv lock --upgrade-package im-sdk`
  (if not already) → `im-cli push` (add `--submit` to chain submit-for-review).
- **Verify:** `im-cli run` runs the new version and streams its console — pass inputs as
  repeated `--input key=value` or `--input-file <file.json>`. That run is the real check
  the migration worked (see [`references/cli-reference.md`](references/cli-reference.md)).

---

## Guardrails

- **Target the latest published SDK** — let `uv lock --upgrade-package im-sdk` resolve it
  off the public index; read the installed version with `importlib.metadata`. Never hardcode
  a number.
- **Migrate before bumping** so you don't conflate a code break with a lock error.
- **`--upgrade-package im-sdk` before every push** when a `pyproject.toml` is present, or
  `uv sync --frozen` fails on a hash drift.
- **Never leave `im-sdk` on a path source at all.** Pointing INTO the monorepo
  (`apps/core-sdk`) breaks because the agent-manager slot has no monorepo checkout; pointing
  at the project's own `vendor/` wheel installs but freezes the project on that wheel. The
  push-safe end state is the **public index** — the slot needs no credential to read it.
- **No credential belongs in `pyproject.toml`.** An index URL carrying userinfo leaks with
  the file the moment the project is shared; the in·manas index needs none.
- **Verify against the installed package, don't guess** — use the bundled
  [`references/sdk-reference.md`](references/sdk-reference.md) and `python -c "import im_sdk …"`
  introspection for anything the bundled snapshot may not cover.
- **Output type stays `string`** — keep `print(json.dumps(<string>))` / the `@im_agent`
  return contract intact.
- **Don't run the agent locally**; verify via push + the Portal Playground/trace.
