smart-org/docs/plan/reports/agent-1-final.md

Agent 1 — final report (org platform)

Branch: dev. Phases 1, 2 (previously merged) plus 3, 4 and 5 (implemented now, reconstructed from the sibling agent1/org-platform branch and reconciled onto dev's shapes).

Summary

The org-platform workstream is complete on dev: a platform owner invites a manager, the manager builds one organization with one application through a five-step wizard, the owner decides which models that organization may use, the organization builds a memory of its own rules / preferences / lessons / code map, and an external AI agent can act inside it through a scoped MCP token the organization's own admin minted. Everything is tenant-scoped, audited, Persian/RTL on the UI side, and no secret reaches a response, a draft, an audit row, a log or an LLM prompt.

apps/api: pytest -q    → 587 passed, 1 skipped
apps/api: ruff check . → All checks passed!
apps/api: mypy app     → Success: no issues found in 147 source files
apps/api: alembic upgrade head / downgrade -1 / upgrade head / check → clean, single head
apps/web: tsc --noEmit → clean · next lint → No ESLint warnings or errors
apps/web: vitest run   → 99 passed (13 files)

Migrations added on dev (the branch's single a1b2c3d4e5f1 was split into one owned migration per phase, chained off dev's own head):

revision	phase	tables
e6f7a8b9c0d1	3	default_model_grants, org_policies
f7a8b9c0d1e2	4	org_memories
a8b9c0d1e2f3	5	mcp_tokens

(Phases 1 and 2 were already on dev: a1b2c3d4e5f1 platform invites, d5e6f7a8b9c0 org setup drafts.)

Endpoints added (all under /api, roles as enforced by the router)

Phase 1 — invites, roles, sharing

POST/GET /admin/platform-invites, POST /admin/platform-invites/{id}/revoke, GET /invites/{token}, POST /invites/accept, GET /auth/me (needs_onboarding), POST /organizations/{id}/transfer-ownership, POST /organizations/{id}/leave, GET/DELETE /organizations/{id}/invites[/{id}], and the /admin/users lifecycle.

Phase 2 — wizard and app profile

GET /setup/catalog, GET/PUT /setup/draft, POST /setup/check-git, POST /setup/check-deploy, POST /setup/complete, GET/PATCH /organizations/{org}/app/profile, PUT /organizations/{org}/app/deploy-target, PUT /organizations/{org}/app/git.

Phase 3 — owner grants and policy

GET /admin/model-grants/{org}, PUT/DELETE /admin/model-grants/{org}/models/{model}, GET /admin/model-grants/{org}/active, GET/PUT/DELETE /admin/default-model-grants[/{model}], GET/PUT /admin/org-policies/{org}.

Phase 4 — memory

GET /organizations/{org}/memory, POST /organizations/{org}/memory, PATCH /organizations/{org}/memory/{id}, POST /organizations/{org}/memory/{id}/pin, .../confirm, DELETE /organizations/{org}/memory/{id}.

Phase 5 — MCP

GET /organizations/{org}/mcp-tokens, POST .../mcp-tokens, DELETE .../mcp-tokens/{id}, GET .../mcp-tokens/settings, GET/PUT /admin/mcp, PUT /admin/mcp/organizations/{id}, and the MCP server at /mcp (python -m app.interfaces.mcp.server, pnpm mcp:dev).

MCP tools: app_get_profile, tasks_list, tasks_get, tasks_create, memory_search, memory_write, knowledge_search, pipeline_status ({"available": false} until Agent 3's tables are wired).

Tables added (all in db/models_org.py)

platform_invites (1) · org_setup_drafts (2) · default_model_grants (3) · org_policies (3) · org_memories (4) · mcp_tokens (5). org_model_grants, which the grants engine reads, is foundation-owned.

Manual QA — the wizard

1. As the owner, /admin/users → «دعوت مدیر جدید» → copy the link.
2. Open it in a private window → «ساخت حساب مدیر» → set a password → land on /onboarding.
3. Step through the five steps; leave at step 2 and reload to confirm the draft resumes. Choose «Git پلتفرم (پیشنهادی)», skip production, create.
4. The success screen shows the demo URL; «برو به مدیر AI» → /manager. The DB has exactly one project with a full profile, and the Null hooks recorded one bootstrap_team and one on_app_created.
5. /admin/model-grants: grant a model to the new org, set its daily cap, revoke.
6. /memory: teach a rule, pin it, confirm a lesson, keep the page open while another tab changes memory — the list refreshes on memory.changed.
7. /settings → «یکپارچه‌سازی (MCP)»: mint a token, copy it once, revoke it. /admin/mcp: flip the global and per-org switches.

CHANGE REQUESTs still open

1. ModelGrantPort should expose get_org_policy(organization_id) (and .mcp_enabled) so Agent 2 reads the policy through the port it already holds.
2. expire_memories() needs a worker hook (billing worker or a new tick in workers/__main__.py).
3. pipeline_status should be pointed at Agent 3's delivery/deploy tables.
4. @agy/contracts lacks memory.changed and the MCP event types; the web compares raw strings.
5. Post-login redirect: an existing manager with needs_onboarding still lands on /dashboard (login/page.tsx and AppShell.tsx are locked); useNeedsOnboarding() is ready to use.
6. build_memory_service / build_model_grant_service live in container_org only; re-export from container.py for one import surface.

Known limitations

• A reflection is not grant-checked (uses pick_for_mode(CHEAP) like the engine).
• expire_memories() has no caller yet.
• pipeline_status is a stub until Agent 3's tables are wired.
• The MCP rate limiter is process-local.
• mcp_gateway_enabled is a process-local setting mutation; a restart re-reads it from the environment.